As of right now this repository only covers the following GMS functionality:
| Function | GitHub | GitLab | Stash |
|---|---|---|---|
| git_deploy_key | X | X | X |
| git_webhook | X | X | X |
Of course it is our intent to provide more coverage of the respective APIs in the future. Please feel free to submit PRs as well.
The following is a table indicating the necessary level of permission needed for the user the authenticating credential(s) are associated with:
| Function | GitHub | GitLab | Stash |
|---|---|---|---|
| git_deploy_key | owners | master | repo_admin |
| git_webhook | owners | master | repo_admin |
Troubleshooting issues when APIs are involved can be painful. Now the advertised providers within this module can pass you useful debugging info when you append the debug argument to your puppet run:
puppet apply --debugor
puppet agent --debugA deploy key is an SSH key that is stored on your server and grants access to a single GitHub repository. This key is attached directly to the repository instead of to a personal user account. Anyone with access to the repository and server has the ability to deploy the project. It is also beneficial for users since they are not required to change their local SSH settings.
Add or remove the deploy key from the GMS
ensure => present,or
ensure => absent,The file Puppet will ensure is provided to the prefered Git management system
path => '/root/.ssh/id_dsa.pub',The project name associated with the project
Be sure to follow the 'userid/repo' format to insure proper operation for GitHub & GitLab. For Stash, only include the project name for this parameter.
project_name => 'abrader/abrader-gms',The URL path to the Git management system server
Both http & https URLs are acceptable.
server_url => 'http://my.internal.gms.server.example.com',If using GitHub Enterprise, add /api/v3 to the URL, and you'll probably need to use https:
server_url => 'https://my.internal.gms.server.example.com/api/v3',The Git Management System you are currently using in reference to the webhook you are managing. Currently only GitHub and GitLab are supported.
provider => 'github',or
provider => 'gitlab',or
provider => 'stash',A unique title for the key that will be provided to the prefered Git management system. This parameter is namevar.
name => 'One of my unique deploy keys',GitHub and GitLab utilize a token based authentication system to access their APIs respectively
The API token generated must have admin permissions and the ability to read/write keys. If the permissions are wrong, you'll likely see the following error message:
...can't convert String into Integer...
This is the unique token you created within your GMS to allow you to interface with the system via the API.
token => 'ABCDEF1234568',The path to a file containing the unique token you created within your GMS to allow you to interface with the system via the API. This is an alternative to, and is mutually exlusive to use of the token parameter.
token_file => '/etc/gitlab/api-token',Stash utilizes a Basic Authentication system as well as an OAuth system for accessing their API respectively. Since OAuth requires a callback URL based system that can not be feasibly implemented by this GMS module, only Basic Authenticaiton is supported.
This is the unique token you created within your GMS to allow you to interface with the system via the API.
username => 'ihavealotof',This is the unique token you created within your GMS to allow you to interface with the system via the API.
password => 'puppet_love',Stash allows a deploy key to be associated with a project (project_name) or with a repository (repo_name). By choosing to omit the repo_name parameter, this module will assume you are associating the SSH key in your git_deploy_key resource block with the project.
repo_name => 'control',git_deploy_key { 'add_deploy_key_to_puppet_control':
ensure => present,
name => $::fqdn,
path => '/root/.ssh/id_dsa.pub',
token => hiera('gitlab_api_token'),
project_name => 'puppet/control',
server_url => 'http://your.internal.github.server.com',
provider => 'github',
}The example below utilizes the optional repo_name parameter to ensure the SSH key in git_deploy_key resouce block below is associated with the repository and not the parent project.
git_deploy_key { 'magical stash deploy key' :
ensure => present,
name => $::fqdn,
username => hiera('stash_api_username'),
password => hiera('stash_api_password'),
project_name => 'puppet',
repo_name => 'control',
path => '/root/.ssh/id_rsa.pub',
server_url => 'http://your.internal.stash.server.com:7990',
provider => 'stash',
}--
A webhook allows repository admins to manage the post-receive hooks for a repository. Very helpful in the case you have many Puppet masters you manage and therefore are responsible for their respective webhooks. This is refers only to respository webhooks and not organizational webhook as offered by Github. If that functionality is ever supported by this project it will be identified separately.
Add or remove the deploy key from the GMS
ensure => present,or
ensure => absent,A unique title for the key that will be provided to the prefered Git management system. This parameter is namevar.
name => 'super_unique_name_for_webhook',The Git Management System you are currently using in reference to the webhook you are managing. Currently only GitHub and GitLab are supported.
provider => 'github',or
provider => 'gitlab',or
provider => 'stash',The URL relating to the webhook. This typically has payload in the name.
webhook_url => 'https://puppetmaster.example.com:8088/payload',This is the unique token you created within your GMS to allow you to interface with the system via the API.
token => 'ABCDEF1234568',The path to a file containing the unique token you created within your GMS to allow you to interface with the system via the API. This is an alternative to, and is mutually exlusive to use of the token parameter.
token_file => '/etc/gitlab/api-token',The project name associated with the project
Be sure to follow the 'userid/repo' format to insure proper operation for GitHub & GitLab. For Stash, only include the project name for this parameter.
project_name => 'control',The URL path to the Git management system server
Both http & https URLs are acceptable.
server_url => 'http://my.internal.gms.server.example.com',GitHub and GitLab utilize a token based authentication system to access their APIs respectively
This is the unique token you created within your GMS to allow you to interface with the system via the API.
token => 'ABCDEF1234568',The path to a file containing the unique token you created within your GMS to allow you to interface with the system via the API. This is an alternative to, and is mutually exlusive to use of the token parameter.
token_file => '/etc/gitlab/api-token',Stash utilizes a Basic Authentication system as well as an OAuth system for accessing their API respectively. Since OAuth requires a callback URL based system that can not be feasibly implemented by this GMS module, only Basic Authenticaiton is supported.
This is the unique token you created within your GMS to allow you to interface with the system via the API.
username => 'ihavealotof',This is the unique token you created within your GMS to allow you to interface with the system via the API.
password => 'puppet_love',Stash allows a deploy key to be associated with a project (project_name) or with a repository (repo_name). By choosing to omit the repo_name parameter, this module will assume you are associating the SSH key in your git_deploy_key resource block with the project.
The name of the repository associated
repo_name => 'control',Boolean value for disabling SSL verification for this webhook. **NOTE: Does not work on Stash **
disable_ssl_verify => true,The gitlab provider sets enable_ssl_verification to false when this attribute is used
The URL in the webhook_url parameter will be triggered when a merge requests event occurs. NOTE: GitLab only
merge_request_events => true,The URL in the webhook_url parameter will be triggered when a tag push event occurs. NOTE: GitLab only
tag_push_events => true,The URL in the webhook_url parameter will be triggered when an issues event occurs. NOTE: GitLab only
issue_events => true,git_webhook { 'web_post_receive_webhook' :
ensure => present,
webhook_url => 'https://puppetmaster.example.com:8088/payload',
token => hiera('gitlab_api_token'),
project_name => 'puppet/control',
server_url => 'http://your.internal.github.server.com',
disable_ssl_verify => true,
provider => 'github',
}git_webhook { 'web_post_receive_webhook' :
ensure => present,
webhook_url => 'https://puppetmaster.example.com:8088/payload',
token => hiera('gitlab_api_token'),
merge_request_events => true,
project_name => 'puppet/control',
server_url => 'http://your.internal.gitlab.server.com',
provider => 'gitlab',
}git_webhook { 'web_post_receive_webhook' :
ensure => present,
webhook_url => 'https://puppetmaster.example.com:8088/payload',
username => hiera('stash_api_username'),
password => hiera('stash_api_password'),
project_name => 'puppet',
repo_name => 'control',
server_url => 'http://your.internal.stash.server.com:7990',
provider => 'stash',
}By heading over the following link:
You should see a screen that resembles something like the following image:
By highlighting only the following options:
- write:repo_hook
- read:repo_hook
- admin:repo_hook
You are limiting this token to only be able to manage webhooks. This may be very beneficial to you if the current tokens available to you entitle too much access. Ultimately, you are puppetizing webhook creation, limiting scope of the token capability only makes sense.
--