Getting started

GitLab CI registration token

To register a Runner with your GitLab CI instance, you need to provide a personal API access token. It can be generated using the profile preferences of your GitLab user account.

Personal API access tokens are created for specific GitLab user accounts and shouldn't be shared in the Ansible inventory or secrets managed by the debops.secret Ansible role. The debops.gitlab_runner role checks the $GITLAB_API_TOKEN environment variable on the Ansible Controller to get the token string and use it for registration.

For convenience, the token can be stored in the .env configuration file at the root of the DebOps project directory, which uses the dotenv format. Variables defined in this file will be automatically sourced in the execution environment when the debops script is invoked. Users can check the runtime environment by executing the command:

debops env

The .env file is ignored by git and shouldn't be committed into the project's version control.

To change the environment variable that holds the API access token, or save the token in Ansible inventory, you can use the gitlab_runner__api_token variable.

Initial configuration

By default, debops.gitlab_runner will configure a single Runner instance which uses a shell executor. If a Docker installation is detected via Ansible local facts, the role will disable the shell executor and configure two Docker executors - one unprivileged, and one privileged. The executors will have a set of tags that identify them, shell executors will have additional tags that describe the host's architecture, OS release, etc.

If the debops.lxc role has been used to configure LXC support on the host, the debops.gitlab_runner will install the vagrant-lxc package and configure sudo support for it. Using a shell executor you can start and stop Vagrant Boxes using LXC containers and execute commands inside them.

If the debops.libvirtd role has been used to configure libvirt support on the host, the debops.gitlab_runner will install the vagrant-libvirt package and configure sudo support for it. Using a shell executor you can start and stop Vagrant Boxes using libvirt and execute commands inside them.

The Runner instances can be configured with variables specified as the keys of the dictionary that holds the specific Runner configuration. If any required keys are not specified, the value of the global variable will be used instead.

Some of the variables will be added together (Docker volumes, for example), so that you can define a list of global values included in all of the Runner instances.

Environment variables

You can use gitlab_runner__environment default variable to specify a custom set of environment variables to configure in a GitLab Runner instance. You can use the global variable, or set the environment at the instance level by specifying it as item.environment variable.

The environment variables can be specified in a different ways:

• a single variable as a string:

  gitlab_runner__environment: 'VARIABLE=value'
  

• a list of environment variables:

  gitlab_runner__environment:
    - 'VARIABLE1=value1'
    - 'VARIABLE2=value2'
  

• a YAML dictionary with variable names as keys and their values as values:

  gitlab_runner__environment:
    VARIABLE1: 'value1'
    VARIABLE2: 'value2'
  

Different specifications cannot be mixed together.

Example inventory

To install GitLab Runner service on a host, it needs to be added to the [debops_service_gitlab_runner] inventory host group:

[debops_service_gitlab_runner]
hostname

Example playbook

Here's an example playbook that can be used to enable and manage the GitLab Runner service on a set of hosts:

---

- name: Manage GitLab Runner service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_gitlab_runner' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::gitlab_runner' ]
      keyring__dependent_apt_keys:
        - '{{ gitlab_runner__keyring__dependent_apt_keys }}'

    - role: gitlab_runner
      tags: [ 'role::gitlab_runner', 'skip::gitlab_runner' ]