{"id":21625684,"url":"https://github.com/bolterrific/puppet-github_inventory","last_synced_at":"2025-10-27T22:31:57.472Z","repository":{"id":94726316,"uuid":"314910416","full_name":"bolterrific/puppet-github_inventory","owner":"bolterrific","description":"Bolt inventory plugin to generate local Targets from a GitHub org's repositories","archived":false,"fork":false,"pushed_at":"2021-07-19T20:31:33.000Z","size":112,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-24T22:41:19.540Z","etag":null,"topics":["bolt","bolt-inventory","devops","github-api","inventory-plugin","orchestration","puppet","puppet-bolt"],"latest_commit_sha":null,"homepage":"","language":"Puppet","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bolterrific.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-21T21:55:25.000Z","updated_at":"2024-12-18T00:43:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"a0783ba4-bf71-45f5-b8b6-92fd4c143788","html_url":"https://github.com/bolterrific/puppet-github_inventory","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolterrific%2Fpuppet-github_inventory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolterrific%2Fpuppet-github_inventory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolterrific%2Fpuppet-github_inventory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolterrific%2Fpuppet-github_inventory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bolterrific","download_url":"https://codeload.github.com/bolterrific/puppet-github_inventory/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244297908,"owners_count":20430347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bolt","bolt-inventory","devops","github-api","inventory-plugin","orchestration","puppet","puppet-bolt"],"created_at":"2024-11-25T01:10:15.665Z","updated_at":"2025-10-27T22:31:57.421Z","avatar_url":"https://github.com/bolterrific.png","language":"Puppet","readme":"# github_inventory\n\n#### Table of Contents\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Description](#description)\n  * [Why is this useful?](#why-is-this-useful)\n  * [How is this useful with Bolt?](#how-is-this-useful-with-bolt)\n* [Setup](#setup)\n  * [Setup Requirements](#setup-requirements)\n  * [Beginning with github_inventory](#beginning-with-github_inventory)\n* [Usage](#usage)\n  * [Using the plugin in a Bolt inventory file](#using-the-plugin-in-a-bolt-inventory-file)\n* [Reference](#reference)\n* [Limitations](#limitations)\n  * [Targets' `.facts` keys use `_name` instead of `name`](#targets-facts-keys-use-_name-instead-of-name)\n  * [Limitations when running the example project](#limitations-when-running-the-example-project)\n* [Development](#development)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Description\n\n**github_inventory** is an [inventory reference plugin] for [Puppet Bolt]. It\nuses the GitHub API to dynamically provide a collection of [`local` transport]\nTargets that represent each repository under a GitHub organization or user.\n\nThis module also contains an example Bolt project with a working\n`inventory.yaml` and several [Bolt plans].\n\n### Why is this useful?\n\nModeling GitHub repositories as Inventory Targets lets admins orchestrate\norg-wide repo operations at scale, using simple \u0026 reusable [Bolt Plans].\n\n### How is this useful with Bolt?\n\nSimplicity, speed, and reusability:  It's trivial to define an inventory, and\nBolt plans are generally concise and legible.  And when using multiple Targets\n(repos) with Bolt plan functions like `run_*()`/`parallelize()`, you get\nconcurrent execution  built-in for free. Plans are easy to wrap up in a module\nand share, so the next time someone has to reset all the required PR checks in\na 200-repo org, they can just pull out the plan and run it on targets from\n_their_ org.\n\nEach `github_inventory` Target describes its repository in its `.facts`, using\nthe same keys as the data structure returned by GitHub's [`/orgs/{org}/repos`]\nor [`/repos/{username}/repos`] endpoints (with [*one* important\nexception](_name-vs-name)).\n\nTargets use the [`local` transport] by default.  This keeps execution as\nfrictionless as possible and ensures that a known version of Ruby (the Bolt\ninterpreter's) is available to execute tasks.  It also also opens the door\nto advanced uses, like git-cloning repos en masse into local working\ndirectories and enforcing file conventions with Tasks and `apply()` blocks.\n\n**Note:** Targets don't use the [`remote` Transport].  It can\nonly run [remote Tasks] (which rules out the built-in [`http_request`]) and\ncan't compile Puppet `apply()` blocks.\n\n## Setup\n\n### Setup Requirements\n\n* [Puppet Bolt 3.0+ or 2.37][bolt], installed from an [OS package][bolt-install] (don't use the RubyGem)\n* A GitHub API personal auth token with sufficient scope\n* The [`octokit` RubyGem][octokit-rb]\n\n### Beginning with github_inventory\n\n1. If you are using [rvm], you **must disable it** before running bolt:\n\n   ```sh\n   rvm use system\n   ```\n\n2. Install the RubyGem dependencies using Bolt's `gem` command\n\n   On most platforms:\n\n   ```sh\n   /opt/puppetlabs/bolt/bin/gem install --user-install -g gem.deps.rb\n   ```\n\n   On Windows:\n\n   ```pwsh\n   \"C:/Program Files/Puppet Labs/Bolt/bin/gem.bat\" install --user-install -g gem.deps.rb\n   ```\n\n3. (If using the example Bolt plans in this module)\n\n   Set the environment variables `GITHUB_ORG` and `GITHUB_API_TOKEN` to\n   appropriate values for your GitHub organization.  The API token needs a\n   scope that can query the organization's repos.\n\n## Usage\n\nTo use this plugin in your own Bolt project, configure it to provide `targets`\nin the [inventory file].\n\n### Using the plugin in a Bolt inventory file\n\nAn example `inventory.yaml` file:\n\n```yaml\ngroups:\n  - name: repo_targets\n    targets:\n      - _plugin: github_inventory  # \u003c- Plugin provides `local` Targets\n        org: simp                  # \u003c- GitHub org with Target repos\n        github_api_token:          # \u003c- API token with scope that can get repos\n          _plugin: env_var         # \u003c- (provided by another Bolt plugin)\n          var: GITHUB_API_TOKEN\n\nconfig:\n  transport: local\n  local:\n    interpreters:\n      .rb: /opt/puppetlabs/bolt/bin/ruby\n    tmpdir:\n     _plugin: env_var\n     var: PWD\n\n```\n\n## Reference\n\nSee [REFERENCE.md](./REFERENCE.md)\n\n## Limitations\n\n### Targets' `.facts` keys use `_name` instead of `name`\n\u003ca class=\"anchor\" id=\"_name-vs-name\"\u003e\u003c/a\u003e\n\n  * `github_inventory` Target facts use the key **`_name`** instead of the\n    repo-level `name` key.\n  * This avoids compilation errors in Puppet `apply()` blocks.\n\n### Limitations when running the example project\n\nIn order to provide the example bolt project in the same module as the\ninventory plugin, `modules/github_inventory/` is symlinked to the repo's\ntop-level directory.  This allows the bolt project to find the inventory\nplugin, but there are some side-effects:\n\n  * Bolt will emit a (benign) warning near the beginning of each run:\n\n    ```\n    The project 'github_inventory' shadows an existing module of the same name [ID: project_shadows_module]\n    ```\n\n  * Git may not establish the symlink properly for Windows users\n\nThis quirk only affects the example bolt project; it will not affect the\ninventory plugin, or running the `github_inventory::` plans from your own Bolt\nproject.\n\n## Development\n\nSubmit PRs on the project's GitHub page.\n\n[Puppet Bolt]: https://puppet.com/docs/bolt/latest/bolt.html\n[Bolt Plans]: https://puppet.com/docs/bolt/latest/plans.html\n[Bolt Tasks]: https://puppet.com/docs/bolt/latest/tasks.html\n[bolt]: https://puppet.com/docs/bolt/latest/bolt.html\n[bolt-install]: https://puppet.com/docs/bolt/latest/bolt_installing.html\n[inventory file]: https://puppet.com/docs/bolt/latest/inventory_file_v2.html\n[inventory reference plugin]: https://puppet.com/docs/bolt/latest/using_plugins.html#reference-plugins\n[`local` transport]: https://puppet.com/docs/bolt/latest/bolt_transports_reference.html#local\n[`remote` transport]: https://puppet.com/docs/bolt/latest/bolt_transports_reference.html#remote\n[octokit-rb]: https://github.com/octokit/octokit.rb\n[rvm]: https://rvm.io\n[`/orgs/{org}/repos`]: https://docs.github.com/en/rest/reference/repos#list-organization-repositories\n[`/repos/{username}/repos`]: https://docs.github.com/en/rest/reference/repos#list-repositories-for-a-user\n[`http_request`]: https://forge.puppet.com/modules/puppetlabs/http_request\n[remote Tasks]: https://puppet.com/docs/bolt/latest/writing_tasks.html#writing-remote-tasks\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolterrific%2Fpuppet-github_inventory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbolterrific%2Fpuppet-github_inventory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolterrific%2Fpuppet-github_inventory/lists"}