REFERENCE.md

Reference

Table of Contents

Tasks

• resolve_reference: Return a GitHub organization's repositories as local inventory targets

Plans

• github_inventory::clone_git_repos: Clone all repos into a local directory
• github_inventory::count: Example plan, prints number of Targets from inventory
• github_inventory::latest_semver_tags: Report the highest SemVer tag for each repo (that has SemVer tags), including information release (if a release exists for that tag) and uplo
• github_inventory::required_checks: List and/or set which PR checks are required on each repo
• github_inventory::update_forked_mirrors: Update default branches & tags on forked GitHub repos (with an option to only affect Puppet module projects for a specific forge org) For ea
• 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

accept_header

Data type: String[1]

Override to request a custom media type from the GitHub API

extra_gem_path

Data type: Optional[String[1]]

Additional GEM_PATH path for ruby gems (to find octokit)

Plans

github_inventory::clone_git_repos

Clone all repos into a local directory

Parameters

The following parameters are available in the github_inventory::clone_git_repos plan:

• targets
• target_dir
• collision_strategy
• clone_protocol
• return_result

targets

Data type: TargetSpec

Name of github_inventory Targets (or inventory group)

Default value: 'github_repos'

target_dir

Data type: Stdlib::Absolutepath

Local directory to clone repos into

Default value: "${system::env('PWD')}/_repos"

collision_strategy

Data type: Enum[fail,skip,overwrite,fetch]

Action to take when a local repo directory already exists

Default value: 'skip'

clone_protocol

Data type: Enum[http,ssh]

'http' or 'ssh'

Default value: 'http'

return_result

Data type: Boolean

When true, plan returns data in a ResultSet

Default value: false

github_inventory::count

Example plan, prints number of Targets from inventory

Parameters

The following parameters are available in the github_inventory::count plan:

• targets
• display_result
• return_result

targets

Data type: TargetSpec

Name of github_inventory Targets (or inventory group)

Default value: 'github_repos'

display_result

Data type: Boolean

When true, plan prints result using out::message

Default value: true

return_result

Data type: Boolean

When true, plan returns data in a ResultSet

Default value: false

github_inventory::latest_semver_tags

Report the highest SemVer tag for each repo (that has SemVer tags), including information release (if a release exists for that tag) and uploaded assets

• Note reports repos with "SemVer-ish" tags (includes /^v/ and /-d$/)

Parameters

The following parameters are available in the github_inventory::latest_semver_tags plan:

• targets
• github_api_token
• display_result
• return_result

targets

Data type: TargetSpec

Name of github_inventory Targets (or inventory group)

Default value: 'github_repos'

github_api_token

Data type: Sensitive[String[1]]

GitHub API token. Doesn't require any scope for public repos.

Default value: (system::env('GITHUB_API_TOKEN'))

display_result

Data type: Boolean

When true, plan prints result using out::message

Default value: true

return_result

Data type: Boolean

When true, plan returns data in a ResultSet

Default value: false

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
• github_api_token
• checks

targets

Data type: TargetSpec

Name of github_inventory Targets (or inventory group)

Default value: 'github_repos'

github_api_token

Data type: Sensitive[String[1]]

GitHub API token. Needs repo scope to see or set checks.

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::update_forked_mirrors

Update default branches & tags on forked GitHub repos (with an option to only affect Puppet module projects for a specific forge org)

For each target repo (provided by github_inventory plugin):

• Clone repo
• (Optional) skip if repo is not a Puppet module for desired forge_org
• Add parent repo as remote, fetchparent's default branch and tags
• (Optional) skip if noop or repo is in noop_repos
• Push parent's default branch to repo (and push tags on branch)
• Ensure repo's default branch matches parent's default branch

Target repos can be fine-tuned in the inventory by using the allow_list/block_list parameters in the github_inventory plugin

Parameters

The following parameters are available in the github_inventory::update_forked_mirrors plan:

• targets
• target_dir
• noop
• noop_repos
• github_api_token
• clone_repos
• forge_org

targets

Data type: TargetSpec

Name of github_inventory Targets (or inventory group)

Default value: 'github_repos'

target_dir

Data type: Stdlib::Absolutepath

Local directory to clone repos into (when clone_repos = true)

Default value: "${system::env('PWD')}/_repos"

noop

Data type: Boolean

When true, all repos will run through all prep steps, but not push up changes.

Default value: true

noop_repos

Data type: Array[String,0]

List of specific repos to always treat as noop, even when noop=false

Default value: []

github_api_token

Data type: Sensitive[String[1]]

Default value: (system::env('GITHUB_API_TOKEN'))

clone_repos

Data type: Boolean

Default value: true

forge_org

Data type: Optional[String[1]]

Default value: 'puppetlabs'

github_inventory::workflows

Return repos with GitHub Actions workflows

Parameters

The following parameters are available in the github_inventory::workflows plan:

• targets
• github_api_token

targets

Data type: TargetSpec

By default: github_repos group from inventory

Default value: 'github_repos'

github_api_token

Data type: Sensitive[String[1]]

GitHub API token. Doesn't require any scope for public repos.

Default value: (system::env('GITHUB_API_TOKEN'))