Forge Home


A Bolt plugin that generates local Targets from GitHub org repositories




517 latest version

5.0 quality score

Version information

  • 0.4.2 (latest)
  • 0.4.1
  • 0.4.0
  • 0.3.0
  • 0.2.1
  • 0.2.0
  • 0.1.0
released Jul 19th 2021
This version is compatible with:
  • Puppet Enterprise 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
  • CentOS
  • resolve_reference
  • clone_git_repos
  • count
  • latest_semver_tags
  • required_checks
  • update_forked_mirrors
  • workflows

Start using this module

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

Add this declaration to your Puppetfile:

mod 'bolterrific-github_inventory', '0.4.2'
Learn more about managing modules with a Puppetfile

Add this module to a Bolt project:

bolt module add bolterrific-github_inventory
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install bolterrific-github_inventory --version 0.4.2

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.



bolterrific/github_inventory — version 0.4.2 Jul 19th 2021


Table of Contents


github_inventory is an inventory reference plugin for Puppet Bolt. It uses the GitHub API to dynamically provide a collection of local transport Targets that represent each repository under a GitHub organization or user.

This module also contains an example Bolt project with a working inventory.yaml and several Bolt plans.

Why is this useful?

Modeling GitHub repositories as Inventory Targets lets admins orchestrate org-wide repo operations at scale, using simple & reusable Bolt Plans.

How is this useful with Bolt?

Simplicity, speed, and reusability: It's trivial to define an inventory, and Bolt plans are generally concise and legible. And when using multiple Targets (repos) with Bolt plan functions like run_*()/parallelize(), you get concurrent execution built-in for free. Plans are easy to wrap up in a module and share, so the next time someone has to reset all the required PR checks in a 200-repo org, they can just pull out the plan and run it on targets from their org.

Each github_inventory Target describes its repository in its .facts, using the same keys as the data structure returned by GitHub's /orgs/{org}/repos or /repos/{username}/repos endpoints (with one important exception).

Targets use the local transport by default. This keeps execution as frictionless as possible and ensures that a known version of Ruby (the Bolt interpreter's) is available to execute tasks. It also also opens the door to advanced uses, like git-cloning repos en masse into local working directories and enforcing file conventions with Tasks and apply() blocks.

Note: Targets don't use the remote Transport. It can only run remote Tasks (which rules out the built-in http_request) and can't compile Puppet apply() blocks.


Setup Requirements

Beginning with github_inventory

  1. If you are using rvm, you must disable it before running bolt:

    rvm use system
  2. Install the RubyGem dependencies using Bolt's gem command

    On 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
  3. (If using the example Bolt plans in this module)

    Set the environment variables GITHUB_ORG and GITHUB_API_TOKEN to appropriate values for your GitHub organization. The API token needs a scope that can query the organization's repos.


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:

  - name: repo_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

  transport: local
      .rb: /opt/puppetlabs/bolt/bin/ruby
     _plugin: env_var
     var: PWD




Targets' .facts keys use _name instead of name

  • github_inventory Target facts use the key _name instead of the repo-level name key.
  • This avoids compilation errors in Puppet apply() blocks.

Limitations when running the example project

In order to provide the example bolt project in the same module as the inventory plugin, modules/github_inventory/ is symlinked to the repo's top-level directory. This allows the bolt project to find the inventory plugin, but there are some side-effects:

  • Bolt will emit a (benign) warning near the beginning of each run:

    The project 'github_inventory' shadows an existing module of the same name [ID: project_shadows_module]
  • Git may not establish the symlink properly for Windows users

This quirk only affects the example bolt project; it will not affect the inventory plugin, or running the github_inventory:: plans from your own Bolt project.


Submit PRs on the project's GitHub page.