Git Management Systems API Types & Providers

A fork of abrader-gms providing:

• Secrets with Github

As of right now this repository only covers the following GMS functionality:

API functions covered

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.

Permissions to use API

The following is a table indicating the necessary level of permission needed for the user the authenticating credential(s) are associated with:

Debugging

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 --debug

or

puppet agent --debug

git_deploy_key

A 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.

GMS agnostic mandatory parameters

ensure

Add or remove the deploy key from the GMS

ensure       => present,

or

ensure       => absent,

path

The file Puppet will ensure is provided to the prefered Git management system

path         => '/root/.ssh/id_dsa.pub',

project_name

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',

server_url

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',

provider

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',

name

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 & GitLab mandatory authentication parameter

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...

token

This is the unique token you created within your GMS to allow you to interface with the system via the API.

token        => 'ABCDEF1234568',

token_file

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 mandatory authentication parameters

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.

username

This is the unique token you created within your GMS to allow you to interface with the system via the API.

username        => 'ihavealotof',

password

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 optional parameter

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

repo_name       => 'control',

A GitHub & GitLab deploy key example

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', 
}

A Stash deploy key example

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',
}

--

git_webhook

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.

GMS system agnostic mandatory parameters

ensure

Add or remove the deploy key from the GMS

ensure       => present,

or

ensure       => absent,

name

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',

provider

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',

webhook_url

The URL relating to the webhook. This typically has payload in the name.

webhook_url  => 'https://puppetmaster.example.com:8088/payload',

token

This is the unique token you created within your GMS to allow you to interface with the system via the API.

token        => 'ABCDEF1234568',

token_file

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',

project_name

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',

server_url

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 & GitLab mandatory authentication parameter

GitHub and GitLab utilize a token based authentication system to access their APIs respectively

token

This is the unique token you created within your GMS to allow you to interface with the system via the API.

token        => 'ABCDEF1234568',

token_file

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 mandatory authentication parameters

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.

username

This is the unique token you created within your GMS to allow you to interface with the system via the API.

username        => 'ihavealotof',

password

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 mandatory parameter

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

The name of the repository associated

repo_name       => 'control',

GitHub & Gitlab optional parameters

disable_ssl_verify

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

GitHub optional Parameters

secret

The secret to set for the webhook. NOTE: GitHub only

secret => 'kl34lkhsdfhiucy4tih,sdjkbhil34',

GitLab optional Parameters

merge_request_events

The URL in the webhook_url parameter will be triggered when a merge requests event occurs. NOTE: GitLab only

merge_request_events => true,

tag_push_events

The URL in the webhook_url parameter will be triggered when a tag push event occurs. NOTE: GitLab only

tag_push_events => true,

issue_events

The URL in the webhook_url parameter will be triggered when an issues event occurs. NOTE: GitLab only

issue_events => true,

GitHub webhook example

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',
  secret             => 's8dofhg7cbyyiuh437cy7wic7y',
}

GitLab webhook example

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',
}

Stash webhook example

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',
}

Limited use access tokens (GitHub only)

By heading over the following link:

Create a GitHub Access Token

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.

--

2016-06-07 - Release 1.0.3

Summary

This release is an attempt to fix the permissions issue users discovered in the previous Forge package mentioned in this issue: Wrong rights on lib/puppet/provider/gms_webhook/github.rb

2016-02-10 - Release 1.0.2

Summary

This release is mainly a wrap of fixes and updates prior to a major rewrite

Fixes

• Deploy Keys
  • All Providers
    • Removed restriction on SSL port
  • Stash
    • Fixed issue with initial deploy key not getting created

2015-10-20 - Release 1.0.1

Summary

This release is purely to expose debugging functionality previously assumed as released. ;)

2015-08-24 - Release 1.0.0

Summary

This release introduces Stash support for both deploy keys and webhooks.

The README has been updated to include the usage notes for these parameters.

Features

• New parameters - Stash
  • username
  • password
  • repo_name

2015-06-12 - Release 0.0.9

Summary

v0.0.8 Tarball on Puppet Forge had bad permissions for the Webhook provider. Thanks to @bhechinger for the heads up.

2015-04-20 - Release 0.0.8

Summary

This release is because I simply missed the updated CHANGELOG when packaging the previous module release.

2015-04-20 - Release 0.0.7

Summary

This release is for the purpose of easing the regex on the git_webhook type so Basic HTTP Auth included with an URL is an accepted parameter.

2015-02-24 - Release 0.0.6

Summary

This release has many new parameters enabling the ability to set different triggers for webhooks on GitLab and disabling ssl checks on GitHub. Minor cleanup as well.

The README has been updated to include the usage notes for these parameters.

Features

• New parameters - GitLab
  • merge_request_events
  • tag_push_events
  • issue_events
• New parameters - GitHub
  • disable_ssl_verify