Git Management Systems API Types & Providers

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

API functions covered

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.

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:

Function	GitHub	GitLab	Stash
git_deploy_key	owners	master	repo_admin
git_webhook	owners	master	repo_admin

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

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

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:

alt text

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.

--

abrader / abrader-gms

readme

Git Management Systems API Types & Providers

API functions covered

Permissions to use API

Debugging

git_deploy_key

GMS agnostic mandatory parameters

ensure

path

project_name

server_url

provider

name

GitHub & GitLab mandatory authentication parameter

token

token_file

Stash mandatory authentication parameters

username

password

Stash optional parameter

repo_name

A GitHub & GitLab deploy key example

A Stash deploy key example

git_webhook

GMS system agnostic mandatory parameters

ensure

name

provider

webhook_url

token

token_file

project_name

server_url

GitHub & GitLab mandatory authentication parameter

token

token_file

Stash mandatory authentication parameters

username

password

Stash mandatory parameter

repo_name

GitHub & Gitlab optional parameters

disable_ssl_verify

GitLab optional Parameters

merge_request_events

tag_push_events

issue_events

GitHub webhook example

GitLab webhook example

Stash webhook example

Limited use access tokens (GitHub only)