Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

gms

Git Management Systems API Types & Providers
Project URLRSS FeedReport issues

6,514 downloads

6,514 latest version

4.3 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 1.0.0 (latest)
released Jan 3rd 2018
This version is compatible with:
  • Puppet Enterprise >= 3.1.3 < 2015.4.0
  • Puppet >= 3.4.3 < 5.0.0
  • , , , , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'beersy-gms', '1.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add beersy-gms
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install beersy-gms --version 1.0.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: git, gitlab, github, stash, gms

Documentation

beersy/gms — version 1.0.0 Jan 3rd 2018

This is a fork of abrader-gms used in the https://github.com/maju6406/pe_code_manager_easy_setup module.

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.

--