How to Make a Custom Gitlab Runner

Table of Contents

Configuration
#

Configure the runner by setting the following environment variables:

Environment Variable	Description	Default Value
`GITLAB_URL`	URL of your GitLab instance	`https://gitlab.com`
`RUNNER_NAME`	Name for the runner	`dockerrunner`
`DEFAULT_IMAGE`	Default Docker image	`alpine`
`PRIVILEGED`	Enable privileged mode (set to `true` to enable)	`false`
`CONCURRENT`	Maximum number of concurrent jobs	`3`
`CHECK_INTERVAL`	Runner polling interval in seconds	`0`
`LOG_LEVEL`	Set log level (`info`, `debug`, etc.)	`info`
`LOG_FORMAT`	Format of logs	`runner`
`METRICS_PORT`	Port for exposing metrics	`9252`
`GITLAB_TOKEN_FILE`	Path to the file containing the GitLab access token	(not required, no default)

Note: GITLAB_ACCESS_TOKEN is derived from the contents of the file specified by GITLAB_TOKEN_FILE. Ensure this token is valid and the file path is correctly set. |

You can customize these values by setting the corresponding environment variables when running your Docker Compose setup.

Prerequisites
#

Docker and Docker Compose installed on your system.
A GitLab account and access token with the necessary permissions to create runners within the target group.

Dockerfile
#

Use this Dockerfile to create a custom GitLab Runner image:

FROM gitlab/gitlab-runner:latest 
COPY ./entrypoint.sh /entrypoint.sh 
RUN chmod +x /entrypoint.sh 

ENTRYPOINT [ "/entrypoint.sh" ]

Entrypoint Script `entrypoint.sh`
#

#!/bin/bash

# Default values
GITLAB_URL="${GITLAB_URL:-https://gitlab.com}"
RUNNER_NAME="${RUNNER_NAME:-dockerrunner}"
DEFAULT_IMAGE="${DEFAULT_IMAGE:-alpine}"
PRIVILEGED="${PRIVILEGED:-false}"
CONCURRENT="${CONCURRENT:-3}"
CHECK_INTERVAL="${GITLAB_URL:-0}"
LOG_LEVEL="${LOG_LEVEL:-info}"
LOG_FORMAT="${LOG_FORMAT:-runner}"
METRICS_PORT="${METRICS_PORT:-9252}"

if [[ -z "${GITLAB_TOKEN_FILE}" ]]; then
    GITLAB_ACCESS_TOKEN=`cat ${GITLAB_TOKEN_FILE}`
fi


if [[ -z "${GITLAB_ACCESS_TOKEN}" ]]; then
    echo "---------------------------------------------------------------------"
    echo "ERROR GITLAB_ACCESS_TOKEN not set!
example:
export GITLAB_ACCESS_TOKEN='token'"
    echo "---------------------------------------------------------------------"
    exit 1
fi
echo "INFO Generating runner config....."

# Generate the config.toml file with the correct token and settings
mkdir -p /etc/gitlab-runner

sed -e "s|{{CONCURRENT}}|$CONCURRENT|" \
    -e "s|{{CHECK_INTERVAL}}|$CHECK_INTERVAL|" \
    -e "s|{{LOG_LEVEL}}|$LOG_LEVEL|" \
    -e "s|{{LOG_FORMAT}}|$LOG_FORMAT|" \
    -e "s|{{METRICS_PORT}}|$METRICS_PORT|" \
    -e "s|{{RUNNER_NAME}}|$RUNNER_NAME|" \
    -e "s|{{GITLAB_URL}}|$GITLAB_URL|" \
    -e "s|{{GITLAB_ACCESS_TOKEN}}|$GITLAB_ACCESS_TOKEN|" \
    -e "s|{{DEFAULT_IMAGE}}|$DEFAULT_IMAGE|" \
    -e "s|{{PRIVILEGED}}|$PRIVILEGED|" \
    /config.template.toml > /etc/gitlab-runner/config.toml



echo "INFO Runner Configuration Generated in /etc/gitlab-runner/config.toml"

if [ $LOG_LEVEL == "debug" ]; then
    echo "DEBUG showing runner config at /etc/gitlab-runner/config.toml"
    cat /etc/gitlab-runner/config.toml
fi

echo "INFO Starting Runner...."
gitlab-runner run

Registration Script `register_runner.sh`
#

The register_runner.sh script is used to register the runner in your GitLab group. Before running the script, you need to configure some variables within it. Here’s how to use the script:

Open the register_runner.sh script in a text editor.
Set the following variables according to your GitLab configuration:
- GROUP_ID: The numerical ID of the GitLab group where the runner will be registered.
- GITLAB_TOKEN: Your GitLab Personal Access Token or Group Access Token with the necessary permissions.
Optionally, you can modify the runner settings by adjusting these variables:
- RUNNER_TAGS: Comma-separated list of tags for the runner.
- RUNNER_DESCRIPTION: Description for the runner.

Here’s an example of how to set the variables:

#!/bin/bash
set -e

# Set your GitLab group ID
GROUP_ID="70780839"

# Set your GitLab Personal Access Token or Group Access Token
GITLAB_TOKEN="YOUR_GITLAB_TOKEN"

# Set runner tags and description
RUNNER_TAGS="labs,docker"
RUNNER_DESCRIPTION="Test runner"

# Register the runner and save the token to a file
RUNNER_TOKEN=$(curl --silent --request POST "https://gitlab.com/api/v4/user/runners" \
    --header "private-token: $GITLAB_TOKEN" \
    --data runner_type=group_type --data group_id=$GROUP_ID --data description="${RUNNER_DESCRIPTION}" --data tag_list="${RUNNER_TAGS}" \
  | jq -r '.token')

echo ${RUNNER_TOKEN} > runner_access_token

Save the changes to the register_runner.sh script.
Make the script executable by running:
```
chmod +x register_runner.sh
```
Run the script using:
```
./register_runner.sh
```
The script will register the runner in your GitLab group and save the runner token to a file named runner_access_token.

Remember to keep your access tokens and sensitive information secure and never share them publicly.

After following these steps, you will have registered a runner in your GitLab group, and the runner token will be saved to the runner_access_token file. You can then use this token in your Docker Compose configuration to set up the GitLab Runner container.

Docker Compose Configuration `docker-compose.yml`
#

version: '3.8'

services:
  gitlab-runner:
    image: registry.gitlab.com/spakl/registry/runner:v1.0.0
    container_name: gitlab-runner
    restart: unless-stopped
    environment:
      - GITLAB_ACCESS_TOKEN=$TOKEN
      - RUNNER_NAME="demo-runner" 
      - "CONCURRENT=3"
      # - LOG_LEVEL=${LOG_LEVEL}
      # - LOG_FORMAT=${LOG_FORMAT}
      # - DEFAULT_IMAGE=${DEFAULT_IMAGE}
      # - PRIVILEGED=${PRIVILEGED}
      # - METRICS_PORT=${METRICS_PORT}
      # - GITLAB_URL=${GITLAB_URL}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      # remember to set GITLAB_TOKEN_FILE=/tmp/token
      # - ./runner_access_token:/tmp/token
    networks:
      - proxy
  
networks:
  proxy:
    external: true

Steps
#

Clone Repository:

Clone this repository to your local machine:
```
git clone <repository-url>
cd <repository-directory>
```
Configure Runner:

Update the values in the entrypoint.sh script and the register_runner.sh script as needed.
Run Registration Script:

Run the register_runner.sh script to generate the runner token:
```
chmod +x register_runner.sh
./register_runner.sh
```
Run Docker Compose:

Start the GitLab Runner container:
```
docker-compose up -d
```
The entrypoint script will generate the runner configuration using the environment variables defined in docker-compose.yml.
Verify Runner:

Log in to your GitLab instance and navigate to your project’s Settings > CI/CD > Runners. You should see the registered runner listed there.

Configuration #

Prerequisites #

Dockerfile #

Entrypoint Script entrypoint.sh #

Registration Script register_runner.sh #

Docker Compose Configuration docker-compose.yml #

Steps #