github_inventory

Table of Contents

• Description
• Setup
  • Setup Requirements
  • Beginning with github_inventory
• Usage
  • Using the plugin in a Bolt inventory file
• Reference
• Limitations
• Development

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)
• A GitHub API personal auth token with sufficient scope
• The octokit RubyGem

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)

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 repo
• github_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'))

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