github_inventory
Version information
This version is compatible with:
- Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
- Puppet >= 4.10.0 < 8.0.0
- , , , , , , ,
Tasks:
- resolve_reference
Plans:
- latest_semver_tags
- required_checks
- workflows
Start using this module
Add this module to your Puppetfile:
mod 'bolterrific-github_inventory', '0.1.0'
Learn more about managing modules with a PuppetfileDocumentation
github_inventory
Table of Contents
Description
github_inventory is an inventory reference plugin for Puppet
Bolt. It uses the GitHub API to dynamically provide a list of local
transport Targets that represent each repository under a GitHub org.
This module also contains an example Bolt project with a working
inventory.yaml
and several Bolt plans.
Setup
Setup Requirements
- Puppet Bolt 2.15+, installed from an OS package (don't use the RubyGem)
- Note: The example
inventory.yaml
assumes Bolt 2.37+ (see comments)
- Note: The example
- A GitHub API personal auth token with sufficient scope
- The
octokit
RubyGem
Beginning with github_inventory
-
If you are using rvm, you must disable it before running bolt:
rvm use system
-
Install the RubyGem dependencies using Bolt's
gem
commandOn most platforms:
/opt/puppetlabs/bolt/bin/gem install --user-install -g gem.deps.rb
On Windows:
"C:/Program Files/Puppet Labs/Bolt/bin/gem.bat" install --user-install -g gem.deps.rb
-
(If using the example Bolt plans in this module)
Usage
To use this plugin in your own Bolt project, configure it to provide targets
in the inventory file.
Using the plugin in a Bolt inventory file
An example inventory.yaml
file:
version: 2
groups:
- name: repo_targets
targets:
- _plugin: github_inventory # <- Plugin provides `local` Targets
org: simp # <- GitHub org with Target repos
github_api_token: # <- API token with scope that can get repos
_plugin: env_var # <- (provided by another Bolt plugin)
var: GITHUB_API_TOKEN
config:
transport: local
local:
interpreters:
.rb: /opt/puppetlabs/bolt/bin/ruby
tmpdir:
_plugin: env_var
var: PWD
Reference
See REFERENCE.md
Limitations
In order to provide an example bolt project in the same module as the inventory
plugin, the example bolt-project.yaml
adds ..
to the modulepath
. This
means that (when using the example bolt project) the folder containing this repo
must be named github_inventory
. There may be other weirdness, depending on
this folders' neighbors.
This quirk only affects the example bolt project; it will not affect the inventory plugin or Bolt plans from your own Bolt projects.
Development
Submit PRs on the project's GitHub page.
Reference
Table of Contents
Tasks
resolve_reference
: Return a GitHub organization's repositories as local inventory targets
Plans
github_inventory::latest_semver_tags
: Report the highest SemVer tag for each repo (that has SemVer tags)github_inventory::required_checks
: List and/or set which PR checks are required on each repogithub_inventory::workflows
: Return repos with GitHub Actions workflows
Tasks
resolve_reference
Return a GitHub organization's repositories as local inventory targets
Supports noop? false
Parameters
org
Data type: String[1]
GitHub org name (or user login) with repos
github_api_token
Data type: Optional[String[1]]
Optional GitHub personal OAuth token, which may be useful to avoid the GitHub API's unauthenticated rate limits
archived_repos
Data type: Boolean
When true, includes archived repositories in results.
private_repos
Data type: Boolean
When true, includes private repositories in results.
allow_list
Data type: Optional[Array[String[1]]]
repo names/patterns to include in inventory, drops all other repos
block_list
Data type: Optional[Array[String[1]]]
repo names/patterns to reject from inventory (can reject targets in allow_list)
transport_type
Data type: String[1]
Bolt Transport type of repository Targets
extra_gem_path
Data type: Optional[String[1]]
Additional GEM_PATH path for ruby gems (to find octokit
)
Plans
github_inventory::latest_semver_tags
Report the highest SemVer tag for each repo (that has SemVer tags)
- Note ONLY reports repos with SemVer tags (ignores
/^v/
and/-d$/
)
Parameters
The following parameters are available in the github_inventory::latest_semver_tags
plan.
targets
Data type: TargetSpec
By default: repo_targets
group from inventory
Default value: 'repo_targets'
github_api_token
Data type: Sensitive[String[1]]
GitHub API token. By default, this will use the GITHUB_API_TOKEN
environment variable.
Default value: (system::env('GITHUB_API_TOKEN'))
github_inventory::required_checks
List and/or set which PR checks are required on each repo
Parameters
The following parameters are available in the github_inventory::required_checks
plan.
targets
Data type: TargetSpec
By default: repo_targets
group from inventory
Default value: 'repo_targets'
github_api_token
Data type: Sensitive[String[1]]
GitHub API token. By default, this will use the GITHUB_API_TOKEN
environment variable.
Default value: (system::env('GITHUB_API_TOKEN'))
checks
Data type: Optional[String[1]]
Optional comma-delimited list of required PR Checks to set on all repos If defined, this will overwrite ALL repos' required PR checks
Default value: undef
github_inventory::workflows
Return repos with GitHub Actions workflows
Parameters
The following parameters are available in the github_inventory::workflows
plan.
targets
Data type: TargetSpec
By default: repo_targets
group from inventory
Default value: get_targets('repo_targets')
github_api_token
Data type: Sensitive[String[1]]
GitHub API token. By default, this will use the GITHUB_API_TOKEN
environment variable.
Default value: (system::env('GITHUB_API_TOKEN'))
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
What are plans?
Modules can contain plans that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog.
0.1.0
Features
- Initial project
- Inventory plugin that returns GitHub org repos as
local
transport Targets - Example Bolt project with working Plans and
inventory.yaml