gitlab_inventory

Table of Contents

• Description
• Setup
  • Setup Requirements
  • Beginning with gitlab_inventory
• 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 2.15+, installed from an OS package (don't use the RubyGem)
  • Note: The example inventory.yaml assumes Bolt 2.37+ (see comments)
• A GitLab API personal auth token with sufficient scope
• The gitlab RubyGem

Beginning with gitlab_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
   

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: 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
        archived_repos: true
        allow_list:
          - '/^pupmod-simp/'
          - 'simp-core'
        block_list:
          - '/_/'
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 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 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

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'

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

0.1.1

Fixes

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

0.1.0

Features

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