infrastructure/roles/gitlab_runner/README.md

gitlab_runner
=========

This will set up a [gitlab-runner](https://docs.gitlab.com/runner/) instance via Docker, that is used to run CI jobs from a GitLab instance.  
Multiple different runners can be created and configured for this runner instance.

**NOTE: Currently this will only allow to configure a docker, shell & docker+machine runner.**

**NOTE2: When deploying docker-machines with the privileged flag enabled, only use this in a trusted environment or set max builds to 1 to prevent malicious actions affecting other builds.**

Requirements
------------

You will need to have docker and docker-compose installed or declared as dependencies with their respective roles.

Role Variables
--------------

**Please look at the [defaults/main.yml](defaults/main.yml) for all available variables and their description.**

**Note: Lines that are commented out via `#` are usually still valid/used variables, but they are not defined by default, so they might enable a feature, when uncommenting/defining them!**  

### Example autoscaling Hetzner-Runner configuration:
```yaml
# This image has the hetzner plugin pre-installed
gitlabrunner_image: "quay.io/shivering-isles/gitlab-hetzner-runner"
gitlabrunner_image_version: 13.6.0

# Extra paths that should be created (eg. to be mounted in the container)
gitlabrunner_extra_paths:
  - "{{ gitlabrunner_install_location }}/hetzner_machine"

gitlabrunner_runners:
    # The URL of the instance that this runner should be associated with
  - gitlab_url: https://gitlab.example.com

    # The token that you received when registering the runner (not the register token!!!)
    # Register a runner first to obtain a token: https://docs.gitlab.com/runner/register/index.html#docker
    # Can be done via the API and the registration token: eg. `curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>"`
    gitlab_token: "ENTER_YOUR_TOKEN_HERE"
    
    # Adjust the name of the runner
    name: "hetzner-docker-auto-scale"

    # Set the docker executor
    executor: "docker+machine"

    # Should the docker runner start containers as privileged? (eg. needed for docker in docker / building with docker etc)
    docker_privileged: true
    # Should the docker socket be mounted into the containers? (SECURITY NOTE: This is critical, as it is effectively the same as root!)
    docker_mount_socket: true

    # The docker-machine driver that should be used (the server provider)
    machine_driver: "hetzner"
    # The template for naming new machines
    machine_name: "machine-%s-gitlab-runner"
    # The maximum amount of builds on a machine (VM) before a new one will be used
    machine_max_builds: 20
    # Time (in seconds) for machine to be in Idle state before it is removed.
    machine_idle_time: 1800
    # Number of machines, that need to be created and are waiting in Idle state.
    machine_idle_count: 0

    # The "MachineOptions" field with parameters that depend on the driver (these usually provide the api token, which machine type is used etc...)
    machine_options:
      hetzner-api-token: "REPLACE_WITH_YOUR_API_TOKEN" # The Hetzner specific API token
      hetzner-image: "debian-10" # The image that should be used for new machines
      hetzner-server-type: "cx11" # The server type (the hardware configuration) to use for a new machine
      hetzner-server-location: "fsn1" # The server location to use for a new machine
      engine-install-url: "https://releases.rancher.com/install-docker/19.03.9.sh" # Workaround until 20.10 gets an update https://github.com/JonasProgrammer/docker-machine-driver-hetzner/issues/54

    # Extra volumes that should be added to the gitlab runner container.
    gitlabrunner_extra_volumes:
      - "./hetzner_machine:/root/.docker/machine"

```

Dependencies
------------

- docker
- docker-compose

License
-------

GPL-3.0-only