{"id":15013935,"url":"https://github.com/voxpupuli/puppet-r10k","last_synced_at":"2025-05-14T17:06:21.508Z","repository":{"id":8359054,"uuid":"9922918","full_name":"voxpupuli/puppet-r10k","owner":"voxpupuli","description":"Setup and configure r10k for use with git based environments in puppet","archived":false,"fork":false,"pushed_at":"2025-05-06T14:07:14.000Z","size":1575,"stargazers_count":97,"open_issues_count":36,"forks_count":169,"subscribers_count":50,"default_branch":"master","last_synced_at":"2025-05-12T04:23:34.166Z","etag":null,"topics":["archlinux-puppet-module","centos-puppet-module","gentoo-puppet-module","hacktoberfest","linux-puppet-module","oraclelinux-puppet-module","puppet","redhat-puppet-module","scientific-puppet-module","ubuntu-puppet-module"],"latest_commit_sha":null,"homepage":"https://forge.puppet.com/puppet/r10k","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxpupuli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"vox-pupuli","github":"voxpupuli"}},"created_at":"2013-05-07T22:18:04.000Z","updated_at":"2025-05-06T14:07:19.000Z","dependencies_parsed_at":"2023-11-09T13:02:20.594Z","dependency_job_id":"4e520b5f-c343-4852-98a6-2b032f2ee9ff","html_url":"https://github.com/voxpupuli/puppet-r10k","commit_stats":{"total_commits":1243,"total_committers":148,"mean_commits":8.39864864864865,"dds":0.7087691069991955,"last_synced_commit":"c522835bf2b3e1f3c1cc0f6df843b5e6338c41e1"},"previous_names":[],"tags_count":100,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-r10k","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-r10k/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-r10k/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-r10k/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxpupuli","download_url":"https://codeload.github.com/voxpupuli/puppet-r10k/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190396,"owners_count":22029632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["archlinux-puppet-module","centos-puppet-module","gentoo-puppet-module","hacktoberfest","linux-puppet-module","oraclelinux-puppet-module","puppet","redhat-puppet-module","scientific-puppet-module","ubuntu-puppet-module"],"created_at":"2024-09-24T19:44:58.246Z","updated_at":"2025-05-14T17:06:21.499Z","avatar_url":"https://github.com/voxpupuli.png","language":"Ruby","funding_links":["https://opencollective.com/vox-pupuli","https://github.com/sponsors/voxpupuli"],"categories":["Modules"],"sub_categories":["Modules Management"],"readme":"# r10k Configuration Module\n[![Puppet Forge](http://img.shields.io/puppetforge/v/puppet/r10k.svg)](https://forge.puppetlabs.com/puppet/r10k)\n[![Build Status](https://travis-ci.org/voxpupuli/puppet-r10k.png?branch=master)](https://travis-ci.org/voxpupuli/puppet-r10k)\n[![Github Tag](https://img.shields.io/github/tag/voxpupuli/puppet-r10k.svg)](https://github.com/voxpupuli/puppet-r10k)\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/voxpupuli/puppet-r10k?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n[![Puppet Forge Downloads](http://img.shields.io/puppetforge/dt/puppet/r10k.svg)](https://forge.puppetlabs.com/puppet/r10k)\n[![Puppet Forge Endorsement](https://img.shields.io/puppetforge/e/puppet/r10k.svg)](https://forge.puppetlabs.com/puppet/r10k)\n\n\n#### Table of Contents\n\n1. [Overview](#overview)\n1. [Module Description - What the module does and why it is useful](#module-description)\n1. [Setup - The basics of getting started with r10k](#setup)\n    * [Prefix Example](#prefix-example)\n    * [What r10k affects](#what-r10k-affects)\n    * [Setup Requirements](#setup-requirements)\n    * [Beginning with r10k](#beginning-with-r10k)\n    * [Using an internal gem server](#using-an-internal-gem-server)\n    * [Mcollective Support](#mcollective-support)\n1. [Webhook Support](#webhook-support)\n1. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n1. [Limitations - OS compatibility, etc.](#limitations)\n1. [Support](#support)\n1. [Development - Guide for contributing to the module](#development)\n1. [Running tests](#running-tests)\n\n## Overview\n\nThis module was built to install and configure r10k. It has a base class to configure r10k to\nsynchronize [dynamic environments](https://github.com/adrienthebo/r10k/blob/master/doc/dynamic-environments.mkd).\nIt also has a series of lateral scripts and tools that assist in general workflow, that will be separated into\ntheir own modules into the future.\n\n## Module Description\n\nThis module is meant to manage the installation and configuration of r10k using multiple installation methods on multiple platforms.\n\n## Setup\n\nPlease refer to the official [r10k docs](https://github.com/puppetlabs/r10k/tree/master/doc) for specific configuration patterns.\n\n### Prefix Example\nInstead of passing a single `remote`, you can pass a puppet [hash](https://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#hashes) as the `sources`\nparameter. This allows you to configure r10k with [prefix](https://github.com/puppetlabs/r10k/blob/910709a2924d6167e2e53e03d64d2cc1a64827d4/doc/dynamic-environments/configuration.mkd#prefix) support. This often used when multiple teams use separate repos, or if hiera and puppet are distributed across two repos.\n\n```puppet\nclass { 'r10k':\n  sources =\u003e {\n    'webteam' =\u003e {\n      'remote'  =\u003e 'ssh://git@github.com/webteam/somerepo.git',\n      'basedir' =\u003e \"${::settings::codedir}/environments\",\n      'prefix'  =\u003e true,\n    },\n    'secteam' =\u003e {\n      'remote'  =\u003e 'ssh://git@github.com/secteam/someotherrepo.git',\n      'basedir' =\u003e '/some/other/basedir',\n      'prefix'  =\u003e true,\n    },\n  },\n}\n```\n### What r10k affects\n\n* Installation of the r10k `gem`\n* Installation of ruby when not using an existing ruby stack i.e. when using `puppet_gem`\n* Management of the `r10k.yaml` in /etc\n* Installation and configuration of a sinatra app when using the [webhook](#webhook-support).\n\n\n#### Version chart\n\nGem installation is pinned to a default version in this module, the following chart shows the gem installation tested with the respective module version.\nYou can override this by passing the `version` parameter.\n\n| Module Version | r10k Version |\n| -------------- | ------------ |\n| v4.0.0+        | [![Latest Version](https://img.shields.io/gem/v/r10k.svg?style=flat-square)](https://rubygems.org/gems/r10k)        |\n| v3.0.x         | 1.5.1        |\n| v2.8.2         | 1.5.1        |\n| v2.7.x         | 1.5.1        |\n| v2.6.5         | 1.4.1        |\n| v2.5.4         | 1.4.0        |\n| v2.4.4         | 1.3.5        |\n| v2.3.1         | 1.3.4        |\n| v2.3.0         | 1.3.2        |\n| v2.2.8         | 1.3.1        |\n| v2.2.x         | 1.1.0        |\n\n\n### Setup Requirements\n\nr10k connects via ssh and does so silently in the background, this typically requires ssh keys to be deployed in advance of configuring r10k. This includes the known host ( public ) key of the respective git server, and the user running r10k's private key used to authenticate git/ssh during background runs.  If you are going to use git repos to retrieve modules, you also need git installed.\n\nHere is an example of deploying the git package and ssh keys needed for r10k to connect to a repo called puppet/control on a gitlab server.  This is helpful when you need to automatically deploy new masters\n\n```puppet\npackage { 'git':\n  ensure =\u003e installed,\n}\n\n#https://docs.puppetlabs.com/references/latest/type.html#sshkey\nsshkey { 'your.internal.gitlab.server.com':\n  ensure =\u003e present,\n  type   =\u003e 'ssh-rsa',\n  target =\u003e '/root/.ssh/known_hosts',\n  key    =\u003e '...+dffsfHQ==',\n}\n\n# Resource git_webhook is provided by https://github.com/bjvrielink/abrader-gms/tree/fixup\ngit_deploy_key { 'add_deploy_key_to_puppet_control':\n  ensure       =\u003e present,\n  name         =\u003e $facts['networking']['fqdn'],\n  path         =\u003e '/root/.ssh/id_dsa.pub',\n  token        =\u003e hiera('gitlab_api_token'),\n  project_name =\u003e 'puppet/control',\n  server_url   =\u003e 'http://your.internal.gitlab.server.com',\n  provider     =\u003e 'gitlab',\n}\n```\nA simple example of creating an ssh private key would use an exec to call `yes y | ssh-keygen -t dsa -C \"r10k\" -f /root/.ssh/id_dsa -q -N ''`.\nThe example above shows using `git_deploy_key` which would deploy that key to the remote git server via its api. This is often required in the programtic creation of compile masters.\n\nGiven r10k will likely be downloading your modules, often on the first server\nit's run on, you will have to `puppet apply` this module to bootstrap this\nconfiguration and allow for ongoing management from there.\n\n### Beginning with r10k\n\nThe simplest example of using it would be to declare a single remote that would be written to r10k.yaml.\n\n```puppet\nclass { 'r10k':\n  remote =\u003e 'git@github.com:someuser/puppet.git',\n}\n```\nThis will configure `/etc/r10k.yaml` and install the r10k gem after installing\nruby using the [puppetlabs/ruby](http://forge.puppetlabs.com/puppetlabs/ruby) module.\n\nIt also supports installation via multiple providers, such as installation in the puppet_enterprise ruby stack in versions less than 3.8\n\nInstalling into the Puppet Enterprise ruby stack in PE 2015.x\n\n```puppet\nclass { 'r10k':\n  remote   =\u003e 'git@github.com:someuser/puppet.git',\n  provider =\u003e 'puppet_gem',\n}\n```\n\n_Note: It is recommended you migrate to using the `pe_r10k` module which is basically\na clone of this modules features and file tickets for anything missing._\n\n\n### Using an internal gem server\n\nDepending on implementation requirements, there are two ways to use alternate gem sources.\n\n#### The gemrc approach\nCreate a global gemrc for Puppet Enterprise to add the local gem source. See http://projects.puppetlabs.com/issues/18053#note-12 for more information.\n\n```puppet\nfile { '/opt/puppet/etc':\n  ensure =\u003e 'directory',\n  owner  =\u003e 'root',\n  group  =\u003e '0',\n  mode   =\u003e '0755',\n}\n\nfile { 'gemrc':\n  ensure  =\u003e 'file',\n  path    =\u003e '/opt/puppet/etc/gemrc',\n  owner   =\u003e 'root',\n  group   =\u003e '0',\n  mode    =\u003e '0644',\n  content =\u003e \"---\\nupdate_sources: true\\n:sources:\\n- http://your.internal.gem.server.com/rubygems/\\n\",\n}\n\nclass { 'r10k':\n  remote   =\u003e 'git@github.com:someuser/puppet.git',\n  provider =\u003e 'pe_gem',\n  require  =\u003e File['gemrc'],\n}\n```\n\n#### The parameter approach\nAdd gem_source to declaration.\n\n```puppet\nclass { 'r10k':\n  remote      =\u003e 'git@github.com:someuser/puppet.git',\n  provider    =\u003e 'gem',\n  gem_source  =\u003e 'https://some.alternate.source.com/',\n}\n```\n\n### Mcollective Support\n![alt tag](https://gist.githubusercontent.com/acidprime/7013041/raw/1a99e0a8d28b13bc20b74d2dc4ab60c7e752088c/post_recieve_overview.png)\n\nAn mcollective agent is included in this module which can be used to do\non demand synchronization. This mcollective application and agent can be\ninstalled on all masters using the following class\n_Note: You must have mcollective already configured for this tool to work,\nPuppet Enterprise users will automatically have mcollective configured._\nThis class does not restart the mcollective or pe-mcollective server on the\nnodes to which it is applied, so you may need to restart mcollective for it\nto see the newly installed r10k agent.\n```puppet\ninclude r10k::mcollective\n```\n\nUsing mco you can then trigger mcollective to call r10k using\n\n```shell\nmco r10k synchronize\n```\n\nYou can sync an individual environment using:\n\n```shell\nmco r10k deploy \u003cenvironment\u003e\n```\nNote: This implies `-p`\n\nYou can sync an individual module using:\n\n```shell\nmco r10k deploy_module \u003cmodule\u003e\n```\n\nIf you are required to run `r10k` as a specific user, you can do so by passing\nthe `user` parameter:\n\n```shell\nmco r10k synchronize user=r10k\n```\n\nTo obtain the output of running the shell command, run the agent like this:\n\n```shell\nmco rpc r10k synchronize -v\n```\n\nAn example post-receive hook is included in the files directory.\nThis hook can automatically cause code to synchronize on your\nservers at time of push in git. More modern git systems use webhooks, for  those see below.\n\n#### Passing proxy info through mco\n\nThe mcollective agent can be configured to supply r10k/git environment `http_proxy`, `https_proxy` variables via the following example\n\n```puppet\nclass { 'r10k::mcollective':\n  http_proxy     =\u003e 'http://proxy.example.lan:3128',\n  git_ssl_no_verify =\u003e 1,\n}\n```\n\n#### Install mcollective support for post receive hooks\nInstall the `mco` command from the puppet enterprise installation directory i.e.\n```shell\ncd ~/puppet-enterprise-3.0.1-el-6-x86_64/packages/el-6-x86_64\nsudo rpm -i pe-mcollective-client-2.2.4-2.pe.el6.noarch.rpm\n```\nCopy the peadmin mcollective configuration and private keys from the certificate authority (puppet master)\n~~~\n/var/lib/peadmin/.mcollective\n/var/lib/peadmin/.mcollective.d/mcollective-public.pem\n/var/lib/peadmin/.mcollective.d/peadmin-cacert.pem\n/var/lib/peadmin/.mcollective.d/peadmin-cert.pem\n/var/lib/peadmin/.mcollective.d/peadmin-private.pem\n/var/lib/peadmin/.mcollective.d/peadmin-public.pem\n~~~\nEnsure you update the paths in _~/.mcollective_ when copying to new users whose name is not peadmin.\nIdeally mcollective will be used with more then just the peadmin user's certificate\nin the future. That said, if your git user does not have a home directory, you can rename .mcollective as /etc/client.cfg\nand copy the certs to somewhere that is readable by the respective user.\n~~~\n/home/gitolite/.mcollective\n/home/gitolite/.mcollective.d/mcollective-public.pem\n/home/gitolite/.mcollective.d/peadmin-cacert.pem\n/home/gitolite/.mcollective.d/peadmin-cert.pem\n/home/gitolite/.mcollective.d/peadmin-private.pem\n/home/gitolite/.mcollective.d/peadmin-public.pem\n~~~\n_Note: PE2 only requires the .mcollective file as the default auth was psk_\n\n#### Removing the mcollective agent\n\n```puppet\nclass { 'r10k::mcollective':\n  ensure =\u003e false,\n}\n```\nThis will remove the mcollective agent/application and ddl files from disk. This likely would be if you are migrating to Code manager in Puppet Enterprise.\n\n## Webhook Support\n\n![alt tag](https://gist.githubusercontent.com/acidprime/be25026c11a76bf3e7fb/raw/44df86181c3e5d14242a1b1f4281bf24e9c48509/webhook.gif)\nFor version control systems that use web driven post-receive processes you can use the example webhook included in this module.\nWhen the webhook receives the post-receive event, it will synchronize environments on your puppet masters.\nThese settings are all configurable for your specific use case, as shown below in these configuration examples.\n\n**NOTE: MCollective and Bolt aren't currently supported with Webhook Go. This will be addressed in a future release of Webhook Go, but is an issue related to the complex nature of Bolt and MCollective/Choria commands that cause issues with the way Go executes shell commands.**\n\n### Webhook Github Enterprise - Non Authenticated\nThis is an example of using the webhook without authentication.\nThe `git_webhook` type will use the [api token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) to add the webhook to the \"control\" repo that contains your puppetfile. This is typically useful when you want to automate the addition of the webhook to the repo.\n\n```puppet\n# Instead of running via mco, run r10k directly\nclass {'r10k::webhook::config':\n  use_mcollective =\u003e false,\n}\n\nclass {'r10k::webhook':\n  ensure         =\u003e true,\n  server         =\u003e {\n    protected =\u003e false,\n  },\n}\n\n# Add webhook to control repository ( the repo where the Puppetfile lives )\n#\n# Resource git_webhook is provided by https://github.com/bjvrielink/abrader-gms/tree/fixup\ngit_webhook { 'web_post_receive_webhook' :\n  ensure       =\u003e present,\n  webhook_url  =\u003e 'http://master.of.masters:8088/payload',\n  token        =\u003e  hiera('github_api_token'),\n  project_name =\u003e 'organization/control',\n  server_url   =\u003e 'https://your.github.enterprise.com',\n  provider     =\u003e 'github',\n}\n\n\n# Add webhook to module repo if we are tracking branch in Puppetfile i.e.\n# mod 'module_name',\n#  :git    =\u003e 'http://github.com/organization/puppet-module_name',\n#  :branch =\u003e 'master'\n# The module name is determined from the repo name , i.e. \u003cpuppet-\u003e\u003cmodule_name\u003e\n# All characters with left and including any hyphen are removed i.e. \u003cpuppet-\u003e\n#\n# Resource git_webhook is provided by https://github.com/bjvrielink/abrader-gms/tree/fixup\ngit_webhook { 'web_post_receive_webhook_for_module' :\n  ensure       =\u003e present,\n  webhook_url  =\u003e 'http://master.of.masters:8088/module',\n  token        =\u003e  hiera('github_api_token'),\n  project_name =\u003e 'organization/puppet-module_name',\n  server_url   =\u003e 'https://your.github.enterprise.com',\n  provider     =\u003e 'github',\n}\n```\n\n### Webhook Github Example - Authenticated\nThis is an example of using the webhook with authentication.\nThe `git_webhook` type will use the [api token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) to add the webhook to the \"control\" repo that contains your puppetfile. This is typically useful when you want to automate the addition of the webhook to the repo.\n\n```puppet\n# Instead of running via mco, run r10k directly\nclass {'r10k::webhook::config':\n  use_mcollective =\u003e false,\n}\n\n# External webhooks often need authentication and ssl and authentication\n# Change the url below if this is changed\n\nclass {'r10k::webhook':\n  ensure =\u003e true,\n  server =\u003e {\n      protected =\u003e true,\n  },\n  tls    =\u003e {\n      enabled     =\u003e true,\n      certificate =\u003e '/path/to/ssl/certificate',\n      key         =\u003e '/path/to/ssl/key',\n  },\n}\n\n# Add webhook to control repository ( the repo where the Puppetfile lives )\n#\n# Resource git_webhook is provided by https://github.com/bjvrielink/abrader-gms/tree/fixup\ngit_webhook { 'web_post_receive_webhook' :\n  ensure             =\u003e present,\n  webhook_url        =\u003e 'https://puppet:puppet@hole.in.firewall:8088/payload',\n  token              =\u003e  hiera('github_api_token'),\n  project_name       =\u003e 'organization/control',\n  server_url         =\u003e 'https://api.github.com',\n  disable_ssl_verify =\u003e true,\n  provider           =\u003e 'github',\n}\n\n# Add webhook to module repo if we are tracking branch in Puppetfile i.e.\n# mod 'module_name',\n#  :git    =\u003e 'http://github.com/organization/puppet-module_name',\n#  :branch =\u003e 'master'\n# The module name is determined from the repo name , i.e. \u003cpuppet-\u003e\u003cmodule_name\u003e\n# All characters with left and including any hyphen are removed i.e. \u003cpuppet-\u003e\n#\n# Resource git_webhook is provided by https://github.com/bjvrielink/abrader-gms/tree/fixup\ngit_webhook { 'web_post_receive_webhook_for_module' :\n  ensure       =\u003e present,\n  webhook_url  =\u003e 'https://puppet:puppet@hole.in.firewall:8088/module',\n  token        =\u003e  hiera('github_api_token'),\n  project_name =\u003e 'organization/puppet-module_name',\n  server_url   =\u003e 'https://api.github.com',\n  disable_ssl_verify =\u003e true,\n  provider     =\u003e 'github',\n}\n```\n\n### Webhook Bitbucket Example\nThis is an example of using the webhook with Atlassian Bitbucket (former Stash).\nRequires the `external hooks` addon by https://marketplace.atlassian.com/plugins/com.ngs.stash.externalhooks.external-hooks/server/overview\nand a specific Bitbucket user/pass.\nRemember to place the `stash_mco.rb` on the bitbucket server an make it executable.\nEnable the webhook over the repository settings `External Async Post Receive Hook`:\n - Executable: e.g. `/opt/atlassian/bitbucket-data/external-hooks/stash_mco.rb` (see hook_exe)\n - Positional parameters: `-t http://git.example.com:8088/payload`\n\n```puppet\n# Add deploy key\ngit_deploy_key { 'add_deploy_key_to_puppet_control':\n  ensure       =\u003e present,\n  name         =\u003e $facts['networking']['fqdn'],\n  path         =\u003e '/root/.ssh/id_rsa.pub',\n  username     =\u003e 'api',\n  password     =\u003e 'pass',\n  project_name =\u003e 'project',\n  repo_name    =\u003e 'puppet',\n  server_url   =\u003e 'https://git.example.com',\n  provider     =\u003e 'stash',\n}\n\n# Add webhook\ngit_webhook { 'web_post_receive_webhook' :\n  ensure       =\u003e present,\n  webhook_url  =\u003e 'https://puppet:puppet@hole.in.firewall:8088/module',\n  password     =\u003e 'pass',\n  username     =\u003e 'api',\n  project_name =\u003e 'project',\n  repo_name    =\u003e 'puppet',\n  server_url   =\u003e 'https://git.example.com',\n  provider     =\u003e 'stash',\n  hook_exe     =\u003e '/opt/atlassian/bitbucket-data/external-hooks/stash_mco.rb',\n}\n```\n\n### Webhook - remove webhook init script and config file.\nFor use when moving to Code Manager, or other solutions, and the webhook should be removed.\n```puppet\nclass {'r10k::webhook':\n  ensure =\u003e false,\n}\n```\n\n### Webhook Prefix Example\n\nPrefixing the command is currently not supported in Webhook Go. This support is expected to be added with a later release.\n\n### Webhook FOSS support with MCollective\n\nMCollective is currently unsupported by Webhook Go. This is expected to be added in a future release and documentation will be updated for that then.\n\n### Webhook Slack notifications\n\nYou can enable Slack notifications for the webhook. You will need a\nSlack webhook URL and the `slack-notifier` gem installed.\n\nTo get the Slack webhook URL you need to:\n\n1. Go to\n   [https://slack.com/apps/A0F7XDUAZ-incoming-webhooks](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks).\n2. Choose your team, press `Configure`.\n3. In configurations press `Add configuration`.\n4. Choose channel, press `Add Incoming WebHooks integration`.\n\nThen configure the webhook to add your Slack Webhook URL.\n\n```puppet\nclass { 'r10k::webhook':\n  . . .\n  chatops =\u003e {\n      enabled    =\u003e true,\n      service    =\u003e 'slack',\n      server_uri =\u003e 'http://slack.webhook/webhook', # mandatory for usage\n      channel    =\u003e '#channel', # defaults to #default\n      user       =\u003e 'r10k', # the username to use\n      auth_token =\u003e \"SLACKAUTHTOKEN\",\n    }\n  }\n```\n\n### Webhook Rocket.Chat notifications\n\nYou can enable Rocket.Chat notifications for the webhook. You will need a\nRocket.Chat incoming webhook URL and the `rocket-chat-notifier` gem installed.\n\nTo get the Rocket.Chat incoming webhook URL you need to:\n\n1. Go to your Rocket.Chat and then select `Administration-Integrations`.\n2. Choose `New integration`.\n3. Choose `Incoming WebHook`. In the webhook form configure:\n  * `Enabled`: `True`.\n  * `Name`: A name for your webhook.\n  * `Post to Channel`: The channel to post to by default.\n4. Save changes with `Save Changes` bottom.\n\nThen configure the webhook to add your Rocket.Chat Webhook URL.\n\n```puppet\nclass { 'r10k::webhook':\n  . . .\n  chatops =\u003e {\n    enabled    =\u003e true,\n    service    =\u003e 'rocketchat',\n    server_uri =\u003e '\u003cyour incoming webhook URL\u003e',\n    user       =\u003e 'username',\n    channel    =\u003e '#channel',\n    auth_token =\u003e 'ROCKETCHATAUTHTOKEN',\n  }\n}\n```\n\n### Webhook Default Branch\n\nThe default branch of the controlrepo is commonly called `production`. This value can be overridden if you use another default branch name, such as `master`.\n\n```puppet\nclass { 'r10k::webhook':\n  ensure =\u003e true,\n  r10k   =\u003e {\n    default_branch =\u003e 'master', # Optional. Defaults to 'production'\n  },\n}\n```\n\n### Triggering the webhook from curl\n\nTo aid in debugging, or to give you some hints as to how to trigger the webhook by unsupported systems, here's a curl command to trigger the webhook to deploy the 'production' environment:\n\n```bash\ncurl --header \"X-Gitlab-Event: Push Hook\" -d '\n  {\n    \"repository\": {\"name\": \"foo\", \"owner\": {\"login\": \"foo\"}},\n    \"ref\": \"production\"\n  }' http://puppet-master.example:4000/api/v1/r10k/environment\n```\n\nIf you are utilizing environment prefixes, you'll need to specify the full environment title (including the prefix) in the 'ref' parameter:\n\n```bash\ncurl --header \"X-Gitlab-Event: Push Hook\" -d '\n  {\n    \"repository\": {\"name\": \"bar\", \"owner\": {\"login\": \"foo\"}},\n    \"ref\": \"bar_production\"\n  }' http://puppet-master.example:4000/api/v1/r10k/environment\n```\n\n### Troubleshooting\n\nIf you're not sure whether your webhook setup works:\n\n- Try to make a GET request to the `heartbeat` endpoint (e.g. http://puppet-master.example:8088/heartbeat).\n  You should see a short JSON answer similar to `{\"status\":\"success\",\"message\":\"running\"}`.\n- Watch the webhook logfile at `/var/log/webhook/access.log`, and send requests (e.g. using curl).\n  Example output if successful:\n\n``` bash\n$ journalctl -f -u webhook-go.service\n...\nJun 05 11:24:54 pop-os systemd[1]: Started Puppet Deployment API Server....\n```\n\n### Docker\n\nIf you are building your image with the puppet, you need to prevent the webhook process from starting as a daemon.\n\nThe following is an example of declaring the webhook without a background mode\n\n```puppet\nclass { 'r10k::webhook':\n  ensure =\u003e false,\n}\n```\n\n### Ignore deploying some environments\n\nSince [2.10.0](https://github.com/voxpupuli/webhook-go/releases/tag/v2.10.0) the webhook has support for ignoring certain branches.\nThis is not yet configureable via the puppet module.\n\n### configuring the webservice/deploy user\n\nFor historic reasons, webhook-go runs as root and executes r10k with the same user.\nVia `r10k::webhook::service_user` you can change the user.\nWith the 15.0.0 release the default will switch from root to puppet.\n\n## Reference\n\n#### Class: `r10k`\nThis is the main public class to be declared , handingly installation and configuration declarations\n\n**Parameters within `r10k`:**\n\n##### `remote`\nA string to be passed in as the source with a hardcode prefix of `puppet`\n\n##### `sources`\nA hash of all sources, this gets read out into the file as yaml. Must not be declared with `remote`\n\n##### `cachedir`\nA single string setting the `r10k.yaml` configuration value of the same name\n\n##### `configfile`\nA path to the configuration file to manage. Be aware Puppet Enterprise 4.0 and higher may conflict if you manage `/etc/puppetlabs/puppet/r10k.yaml`\n\n##### `version`\nA value passed to the package resource for managing the gem version\n\n##### `modulepath`\nDeprecated: for older [configfile](https://docs.puppetlabs.com/puppet/latest/reference/environments_classic.html) environments configuration of modulepath in puppet.conf\n\n##### `manage_modulepath`\nDeprecated: declare a resource for managing `modulepath` in Puppet.conf\n\n##### `proxy`\nA string setting the`r10k.yaml` configuration value of the same name\n\n##### `gem_source`\nAn optional string specifying location to retrieve gem\n\n##### `pool_size`\nInteger defining how many threads should be spawn while updating modules. Only available for r10k \u003e= 3.3.0.\n\n##### `r10k_basedir`\n\n##### `package_name`\nThe name of the package to be installed via the provider\n\n##### `provider`\nThe supported installation modes for this module\n\n* bundle\n* puppet_gem\n* gem\n\n##### `install_options`\nOptions to pass to the `provider` declaration\n\n##### `mcollective`\nInstall mcollective application and agents. This does NOT configure mcollective automatically\n\n##### `manage_configfile_symlink`\nManage a symlink to the configuration file, for systems installed in weird file system configurations\n\n##### `git_settings`\nThis is the `git:` key in r10k, it accepts a hash that can be used to configure\nrugged support.\n\n```puppet\n    $git_settings = {\n      'provider'    =\u003e 'rugged',\n      'private_key' =\u003e '/root/.ssh/id_rsa',\n    }\n\n    class {'r10k':\n      remote       =\u003e 'git@github.com:acidprime/puppet.git',\n      git_settings =\u003e $git_settings,\n    }\n```\n\n##### `forge_settings`\nThis is the `forge:` key in r10k, it accepts a hash that contains settings for downloading modules from the Puppet Forge.\n\n```puppet\n    $forge_settings = {\n      'proxy'   =\u003e 'https://proxy.example.com:3128',\n      'baseurl' =\u003e 'https://forgeapi.puppetlabs.com',\n    }\n\n    class {'r10k':\n      remote         =\u003e 'git@github.com:acidprime/puppet.git',\n      forge_settings =\u003e $forge_settings,\n    }\n```\n\n##### `deploy_settings`\nThis is the `deploy:` key in r10k, it accepts a hash that contains setting that control how r10k code deployments behave. Documentation for the settings can be found [here](https://docs.puppet.com/pe/latest/r10k_custom.html#deploy).\n\n```puppet\n    $deploy_settings = {\n      'purge_levels' =\u003e ['puppetfile'],\n    }\n\n    class {'r10k':\n      remote          =\u003e 'git@github.com:voxpupuli/puppet.git',\n      deploy_settings =\u003e $deploy_settings,\n    }\n```\n\n##### `configfile_symlink`\nboolean if to manage symlink\n\n##### `include_prerun_command`\nDeprecated: Add [prerun_command](https://docs.puppetlabs.com/references/latest/configuration.html#preruncommand) to puppet.conf to run r10k when the agent on the master runs.\nSuggest instead declaring `r10k::postrun_command ` as that will run after the agent runs which prevents r10k from stopping configuration management of masters from occurring as it does with `prerun_command`s\n\n##### `include_postrun_command`\n```\nr10k::include_postrun_command: true\n```\n\nThe concept here is that this is declared on the puppet master(s) that have\nbeen configured with r10k. This will cause r10k to synchronize after each\npuppet run. Any errors synchronizing will be logged to the standard puppet run.\n\n## Limitations\nThe 4.1.x release *deprecates* support for:\n* Puppet 3\n* Ruby 1.9.3\n\nThese items are planned for removal in v5.0.0.\n\n## Support\n\nPlease log tickets and issues at our [Projects site](https://github.com/voxpupuli/puppet-r10k/issues)\n\n## Development\n\n### Contributing\n\nModules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.\n\nWe want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for more details.\n\n### Running tests\n\nThis project contains tests for [rspec-puppet](http://rspec-puppet.com/) to\nverify functionality. For in-depth information please see their respective\ndocumentation, as well as [CONTRIBUTING](.github/CONTRIBUTING.md).\n\nQuickstart:\n\n```\n    gem install bundler\n    bundle install --without system_tests\n    bundle exec rake test\n    bundle exec rake lint\n```\n\nCheck the .travis.yml for supported Operating System Versions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-r10k","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxpupuli%2Fpuppet-r10k","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-r10k/lists"}