Gitlab-CI runner module for Puppet

Table of Contents

1. Overview
2. Usage - Configuration options and additional functionality
3. Limitations - OS compatibility, etc.

Overview

This module installs and configures the Gitlab CI Runner Package or nodes.

Usage

Here is an example how to configure Gitlab CI runners using Hiera:

To use the Gitlab CI runners it is required to have the puppetlabs/docker module.

$manage_docker can be set to false if docker is managed externally.

gitlab_ci_runner::concurrent: 4

gitlab_ci_runner::check_interval: 4

gitlab_ci_runner::metrics_server: "localhost:8888"

gitlab_ci_runner::manage_docker: true

gitlab_ci_runner::config_path: "etc/gitlab-runner/config.toml"

gitlab_ci_runner::runners:
  test_runner1:{}
  test_runner2:{}
  test_runner3:
    url: "https://git.alternative.org/ci"
    registration-token: "abcdef1234567890"
    tags-list: "aws,docker,example-tag"

gitlab_ci_runner::runner_defaults:
  url: "https://git.example.com/ci"
  registration-token: "1234567890abcdef"
  executor: "docker"
  docker-image: "ubuntu:focal"
  builds_dir: "/tmp"
  cache_dir: "/tmp"

To unregister a specific runner you may use ensure param:

gitlab_ci_runner::runners:
  test_runner1:{}
  test_runner2:{}
  test_runner3:
    url: "https://git.alternative.org/ci"
    registration-token: "abcdef1234567890"
    ensure: absent

Limitations

The Gitlab CI runner installation is at the moment only tested on:

• CentOS 6/7/8
• Debian 8/9/10
• Ubuntu 16.04/18.04

A runner configuration is currently only applied if the specific runner does not exist in the config file.

Reference

Table of Contents

Classes

Public Classes

• gitlab_ci_runner: This module installs and configures Gitlab CI Runners.

Private Classes

• gitlab_ci_runner::config: Manages the configuration of Gitlab runner
• gitlab_ci_runner::install: Manages the package of Gitlab runner
• gitlab_ci_runner::repo: Manages the repository for Gitlab runner
• gitlab_ci_runner::service: Manages the service of Gitlab runner

Defined types

• gitlab_ci_runner::runner: This module installs and configures Gitlab CI Runners.

Tasks

• register_runner: Registers a runner on a Gitlab instance.
• unregister_runner: Unregisters a runner from a Gitlab instance.

Classes

gitlab_ci_runner

This module installs and configures Gitlab CI Runners.

Examples

Simple runner registration

class { 'gitlab_ci_runner':
  runners => {
     example_runner => {
         'registration-token' => 'gitlab-token',
         'url'                => 'https://gitlab.com',
         'tag-list'           => 'docker,aws',
     },
  },
}

Parameters

The following parameters are available in the gitlab_ci_runner class.

runners

Data type: Hash

Hashkeys are used as $title in runners.pp. The subkeys have to be named as the parameter names from ´gitlab-runner register´ command cause they're later joined to one entire string using 2 hyphen to look like shell command parameters. See ´https://docs.gitlab.com/runner/register/#one-line-registration-command´ for details.

Default value: {}

runner_defaults

Data type: Hash

A hash with defaults which will be later merged with $runners.

Default value: {}

xz_package_name

Data type: String

The name of the 'xz' package. Needed for local docker installations.

concurrent

Data type: Optional[Integer]

Limits how many jobs globally can be run concurrently. The most upper limit of jobs using all defined runners. 0 does not mean unlimited!

Default value: undef

builds_dir

Data type: Optional[String]

Absolute path to a directory where builds will be stored in context of selected executor (Locally, Docker, SSH).

Default value: undef

cache_dir

Data type: Optional[String]

Absolute path to a directory where build caches will be stored in context of selected executor (locally, Docker, SSH). If the docker executor is used, this directory needs to be included in its volumes parameter.

Default value: undef

metrics_server

Data type: Optional[Pattern[/.*:.+/]]

(Deprecated) [host]: to enable metrics server as described in https://docs.gitlab.com/runner/monitoring/README.html#configuration-of-the-metrics-http-server.

Default value: undef

listen_address

Data type: Optional[Pattern[/.*:.+/]]

Address (:) on which the Prometheus metrics HTTP server should be listening.

Default value: undef

sentry_dsn

Data type: Optional[String]

Enable tracking of all system level errors to sentry.

Default value: undef

manage_docker

Data type: Boolean

If docker should be installs (uses the puppetlabs-docker).

Default value: false

manage_repo

Data type: Boolean

If the repository should be managed.

Default value: true

package_ensure

Data type: String

The package 'ensure' state.

Default value: installed

package_name

Data type: String

The name of the package.

Default value: 'gitlab-runner'

repo_base_url

Data type: Stdlib::HTTPUrl

The base repository url.

Default value: 'https://packages.gitlab.com'

repo_keyserver

Data type: Optional[Stdlib::Fqdn]

The keyserver which should be used to get the repository key.

Default value: undef

config_path

Data type: String

The path to the config file of Gitlab runner.

Default value: '/etc/gitlab-runner/config.toml'

Defined types

gitlab_ci_runner::runner

This module installs and configures Gitlab CI Runners.

Examples

Simple runner registration

gitlab_ci_runner::runner { example_runner:
  config => {
    'registration-token' => 'gitlab-token',
    'url'                => 'https://gitlab.com',
    'tag-list'           => 'docker,aws',
  },
}

Parameters

The following parameters are available in the gitlab_ci_runner::runner defined type.

config

Data type: Hash

Hash with configuration options. See https://docs.gitlab.com/runner/configuration/advanced-configuration.html for all possible options.

ensure

Data type: Enum['present', 'absent']

If the runner should be 'present' or 'absent'. Will register/unregister the runner from Gitlab.

Default value: 'present'

runner_name

Data type: String[1]

The name of the runner.

Default value: $title

binary

Data type: String[1]

The name of the Gitlab runner binary.

Default value: 'gitlab-runner'

Tasks

register_runner

Registers a runner on a Gitlab instance.

Supports noop? false

Parameters

url

Data type: String[1]

The url to your Gitlab instance. Please only provide the host part (e.g https://gitlab.com)

token

Data type: String[1]

Registration token.

description

Data type: Optional[String[1]]

Runners description.

info

Data type: Optional[Hash]

Runners metadata.

active

Data type: Optional[Boolean]

Whether the Runner is active.

locked

Data type: Optional[Boolean]

Whether the Runner should be locked for current project.

run_untagged

Data type: Optional[Boolean]

Whether the Runner should handle untagged jobs.

tag_list

Data type: Optional[Array[String[1]]]

List of Runners tags.

access_level

Data type: Optional[Enum['not_protected', 'ref_protected']]

The access_level of the runner.

maximum_timeout

Data type: Optional[Integer[1]]

Maximum timeout set when this Runner will handle the job.

unregister_runner

Unregisters a runner from a Gitlab instance.

Supports noop? false

Parameters

url

Data type: String[1]

The url to your Gitlab instance. Please provide the host part only! (e.g https://gitlab.com)

token

Data type: String[1]

Runners authentication token.

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v3.0.0 (2020-09-15)

Full Changelog

Breaking changes:

• Make manage_docker optional and include the docker module if used #80 (baurmatt)

Implemented enhancements:

• Allow management of check_interval config setting #91 (tuxmea)
• Add support for CentOS 8, Debian 10 #87 (dhoppe)

Merged pull requests:

• Fix CI problems #89 (carljohnstone)
• Switch from Ubuntu Trusty to Ubuntu Focal #88 (carljohnstone)
• Use voxpupuli-acceptance #83 (ekohl)

v2.1.0 (2020-04-07)

Full Changelog

Implemented enhancements:

• Use new gitlab gpg keys for package management #84 (dhoppe)

Closed issues:

• Release new version #58

v2.0.0 (2020-02-06)

Full Changelog

Breaking changes:

• Completely refactor gitlab_ci_runner::runner #74 (baurmatt)
• drop Ubuntu support #60 (bastelfreak)
• modulesync 2.7.0 and drop puppet 4 #39 (bastelfreak)

Implemented enhancements:

• Module should manage build_dir and cache_dir #33
• Add bolt task to register/unregister a runner #73 (baurmatt)
• Add Amazon Linux support (RedHat OS Family) #70 (bFekete)
• Add listen_address parameter #65 (baurmatt)
• Add custom repo #48 (lupintrd)
• Add support for current releases #41 (dhoppe)
• Fix xz dependency on RedHat systems #40 (smortex)

Fixed bugs:

• Multiple tags in tag-list are ignored only last is respected #37
• The package xz-utils is xz on CentOS #25
• Fix bugs which got introduced by to runner.pp refactoring #76 (baurmatt)
• Fix runner name in unregister command #57 (dcasella)
• Use '=' to avoid errors while joining cmd options+values #31 (ajcollett)

Closed issues:

• registration_token containing undescore gets modified #61
• /etc/gitlab-runner/config.toml must exist #35
• Metrics server and Session listen address' #26

Merged pull requests:

• Extract resources out of init.pp #72 (baurmatt)
• Allow puppetlabs/stdlib 6.x #71 (dhoppe)
• Switch to puppet-strings for documentation #64 (baurmatt)
• Use grep with --fixed-strings to avoid issues with some characters in the runner's names #63 (Farfaday)
• Extend documentation in README with example tags #59 (jacksgt)
• add limitations about the runner configurations #56 (thde)
• ensure config exists #53 (thde)
• Added suport for configuring sentry_dsn #44 (schewara)
• Allow ensure => "present" for runners #36 (evhan)
• allow build_dir and cache_dir to be managed #34 (slmagus)

v1.0.0 (2018-11-21)

Full Changelog

This is the first release of puppet/gitlab_ci_runner. The functionality in this module was previously part of puppet/gitlab

Fixed bugs:

• Fix (un-)registering runner with similar names #22 (elkangaroo)

Closed issues:

• Import cirunner code from voxpupuli/puppet-gitlab module #12
• remove apt from dependencies #4
• Update license in metadata.json and add LiCENSE file #3
• Update ruby version in Dockerfile #2

Merged pull requests:

• modulesync 2.1.0 and allow puppet 6.x #23 (bastelfreak)
• allow puppetlabs/stdlib 5.x #19 (bastelfreak)
• initial import of puppet code #13 (LongLiveCHIEF)
• remove apt from metadata.json dependencies #10 (LongLiveCHIEF)
• Update ruby version in dockerfile #8 (LongLiveCHIEF)
• fix module name in metadata.json #6 (LongLiveCHIEF)
• update licensing information #5 (LongLiveCHIEF)
• modulesync setup #1 (LongLiveCHIEF)

* This Changelog was automatically generated by github_changelog_generator