gitlab_inventory

Table of Contents

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

Description

gitlab_inventory is an inventory reference plugin for Puppet Bolt. It uses the GitLab API to dynamically provide a list of local transport Targets that represent each project under a GitLab group.

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

Setup

Setup Requirements

• Puppet Bolt
  • Preferred version: Bolt 3.17+
  • Strict minimum is Bolt 2.15+ (untested)
  • Bolt must be installed from an OS package (don't use the bolt RubyGem)
  • Note: The example inventory.yaml assumes Bolt 2.37+ (see comments)
• A GitLab API personal auth token with sufficient scope

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: gitlab_projects
    targets:
      - _plugin: gitlab_inventory  # <- Plugin provides `local` Targets
        group:                     # <- GitLab group with Target repos
          _plugin: env_var
          var: GITLAB_GROUP
          default: simp
        # some optional parameters:
        gitlab_api_token:          # <- API token with scope that can get repos
          _plugin: env_var         # <- (provided by another Bolt plugin)
          var: GITLAB_API_PRIVATE_TOKEN
        gitlab_api_endpoint: https://gitlab.com/api/v4
        archived_repos: true
        allow_list:
          - '/^pupmod-simp/'
          - 'simp-core'
        block_list:
          - '/gitlab-oss/'
config:
  transport: local
  local:
    bundled-ruby: true
    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 gitlab_inventory. There may be other weirdness, depending on whether neighboring directories contain Bolt projects or Puppet modules.

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 at the project's GitHub repository.

Reference

Table of Contents

Tasks

• resolve_reference: Return a GitLab organization's projects as local inventory targets

Plans

• gitlab_inventory::count: Example plan, prints number of Targets from inventory
• gitlab_inventory::latest_semver_tags: Report the highest SemVer tag for each repo (that has SemVer tags)
• gitlab_inventory::required_checks: List and/or set which PR checks are required on each repo
• gitlab_inventory::workflows: Return repos with GitLab Actions workflows

Tasks

resolve_reference

Return a GitLab organization's projects as local inventory targets

Supports noop? false

Parameters

group

Data type: String[1]

GitLab group name (or user login) with repos

gitlab_api_endpoint

Data type: String[1]

URL of GitLab instance's base API endpoint

gitlab_api_token

Data type: Optional[String[1]]

Optional GitLab personal OAuth token, which may be useful to avoid the GitLab API's unauthenticated rate limits

archived_repos

Data type: Boolean

When true, includes archived projects in results.

visibility

Data type: Optional[Array[Enum['public','internal','private']]]

When set, filters projects by visibility

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

gitlab_inventory::count

Example plan, prints number of Targets from inventory

Parameters

The following parameters are available in the gitlab_inventory::count plan.

targets

Data type: TargetSpec

By default: repo_targets group from inventory

Default value: 'repo_targets'

gitlab_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 gitlab_inventory::latest_semver_tags plan.

targets

Data type: TargetSpec

By default: repo_targets group from inventory

Default value: 'repo_targets'

gitlab_api_token

Data type: Sensitive[String[1]]

GitLab API token. By default, this will use the GITHUB_API_TOKEN environment variable.

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

gitlab_inventory::required_checks

List and/or set which PR checks are required on each repo

Parameters

The following parameters are available in the gitlab_inventory::required_checks plan.

targets

Data type: TargetSpec

By default: repo_targets group from inventory

Default value: 'repo_targets'

gitlab_api_token

Data type: Sensitive[String[1]]

GitLab 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

gitlab_inventory::workflows

Return repos with GitLab Actions workflows

Parameters

The following parameters are available in the gitlab_inventory::workflows plan.

targets

Data type: TargetSpec

By default: repo_targets group from inventory

Default value: get_targets('repo_targets')

gitlab_api_token

Data type: Sensitive[String[1]]

GitLab 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.2.1

Fixed

• Report connection errors & details at the time they occur

0.2.0

Added

• Inventory task is now completely self-sufficient
  • All dependencies are provided by Bolt's AIO package
  • This should make it simpler to manage network-isolated GitLab instances―you just need this repo and Bolt
• Added a new example Bolt plan, gitlab_inventory::clone_git_repos

Removed

• Removed dependency on external gems:
  • Removed dependency on gitlab RubyGem.
  • Removed requirement to run gem install --user-install -g gems.deps.rb
• From now on, all Gitlab API calls are handled via Bolt's natively vendored gems (like Faraday).

Fixed

• The visibility inventory parameter no longer fails when given a String (String must be one of: public, internal, or private)

0.1.1

Fixed

• (Forge-only) Removed broken plan files from tarball published to the Forge

0.1.0

Added

• Initial project
• Inventory plugin that returns GitLab group projects as local transport Targets
• Example Bolt project with working Plans and inventory.yaml