# Reference ## Table of Contents ### Tasks * [`resolve_reference`](#resolve_reference): Return a GitHub organization's repositories as local inventory targets ### Plans * [`github_inventory::clone_git_repos`](#github_inventoryclone_git_repos): Clone all repos into a local directory * [`github_inventory::count`](#github_inventorycount): Example plan, prints number of Targets from inventory * [`github_inventory::latest_semver_tags`](#github_inventorylatest_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`](#github_inventoryrequired_checks): List and/or set which PR checks are required on each repo * [`github_inventory::update_forked_mirrors`](#github_inventoryupdate_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`](#github_inventoryworkflows): 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`](#targets) * [`target_dir`](#target_dir) * [`collision_strategy`](#collision_strategy) * [`clone_protocol`](#clone_protocol) * [`return_result`](#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`](#targets) * [`display_result`](#display_result) * [`return_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`](#targets) * [`github_api_token`](#github_api_token) * [`display_result`](#display_result) * [`return_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`](#targets) * [`github_api_token`](#github_api_token) * [`checks`](#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`](#targets) * [`target_dir`](#target_dir) * [`noop`](#noop) * [`noop_repos`](#noop_repos) * [`github_api_token`](#github_api_token) * [`clone_repos`](#clone_repos) * [`forge_org`](#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`](#targets) * [`github_api_token`](#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'))`