infrastructure/roles/gitlab-runner/README.md

gitlab-runner
=========

This will setup a [gitlab-runner](https://docs.gitlab.com/runner/) instance via Docker, that is used to run CI jobs from a Gitlab instance.  
By default a gitlab-runner with the docker executor is setup, that can be used to build various jobs (but is unpriviledged by default!).  

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

**NOTE2: This will by default deploy docker machines with the priveleged flag enabled, so 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.2.2

# Adjust the name of the runner
gitlabrunner_name: "hetzner-docker-auto-scale"

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

# Should the docker runner start containers as privileged? (eg. needed for docker in docker / building with docker etc)
gitlabrunner_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!)
gitlabrunner_docker_mount_socket: true

# The docker-machine driver that should be used (the server provider)
gitlabrunner_machine_driver: "hetzner"
# The template for naming new machines
gitlabrunner_machine_name: "machine-%s-gitlab-runner-{{ gitlabrunner_machine_options['hetzner-server-type'] }}"

# The "MachineOptions" field with parameters that depend on the driver (these usually provide the api token, which machine type is used etc...)
gitlabrunner_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

```

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

- docker
- docker-compose

License
-------

GPL-3.0-only