Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.futurex.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What is GitLab Runner?

GitLab Runner executes your CI/CD pipeline jobs either on a dedicated host outside your GitLab instance or on the same host as your GitLab instance. For CryptoHub code signing, you need a runner that can pull Docker images from public registries (i.e., Docker Hub and the Futurex public registry), then execute build and signing jobs in isolated containers. This ensures clean, reproducible builds and keeps your signing credentials off developer workstations. In this section, you install GitLab Runner on a Linux machine, register it with your GitLab project, and configure the Docker executor to handle both MinGW cross-compilation jobs and CryptoHub CLI signing jobs. Once complete, any pipeline run will automatically route build jobs (tagged mingw) and sign jobs (tagged codesign) to this runner.

​
Install Docker

Why: GitLab Runner’s Docker executor spawns ephemeral containers for each job. Without Docker, the runner cannot execute pipeline jobs. If Docker isn’t installed, add the official Docker repository and install:
As an extra precausion, run the following command to uninstall all conflicting packages before proceeding with the below commands to install Docker.
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
Bash
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
Verify Docker is running:
Bash
sudo docker run hello-world

​
Install GitLab Runner

Add the GitLab Runner repository and install:
Bash
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install -y gitlab-runner
Verify the installation:
Bash
gitlab-runner --version
Expected output: Version 17.x.x (or newer)

​
Register the runner with your GitLab instance

Run the registration wizard:
Bash
sudo gitlab-runner register

Provide the following values when prompted:

<table>
  <thead>
    <tr>
      <th>Prompt</th>
      <th>Value</th>
      <th>Notes</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>GitLab instance URL</strong></td>
      <td><code>https://gitlab.com</code> (or your instance URL)</td>
      <td>Include <code>https://</code></td>
    </tr>
    <tr>
      <td><strong>Registration token</strong></td>
      <td><code>[token from GitLab UI]</code></td>
      <td>Find in <strong>Settings > CI/CD > Runners</strong></td>
    </tr>
    <tr>
      <td><strong>Description</strong></td>
      <td><code>codesign-runner</code></td>
      <td>Appears in GitLab UI; be descriptive</td>
    </tr>
    <tr>
      <td><strong>Tags</strong></td>
      <td><code>mingw,codesign</code></td>
      <td>Comma-separated; critical for job routing</td>
    </tr>
    <tr>
      <td><strong>Maintenance note</strong></td>
      <td><code>[leave empty]</code></td>
      <td>Optional; press Enter to skip</td>
    </tr>
    <tr>
      <td><strong>Executor</strong></td>
      <td><code>docker</code></td>
      <td>Type <code>docker</code> exactly</td>
    </tr>
    <tr>
      <td><strong>Default Docker image</strong></td>
      <td><code>alpine:latest</code></td>
      <td>Fallback image; rarely used in practice</td>
    </tr>
  </tbody>
</table>

**Why tags matter:** GitLab routes jobs to runners based on tags. A job tagged `mingw` will only run on runners with that tag. No tag match = job stuck in "pending" until the heat death of the universe.

**Example registration session:**

Runtime platform: arch=amd64 os=linux
Enter the GitLab instance URL: https://gitlab.com
Enter the registration token: glrt-a8c3eFx9...
Enter a description: codesign-runner
Enter tags for the runner (comma-separated): mingw,codesign
Enter optional maintenance note: 
Registering runner... succeeded
Enter an executor: docker
Enter the default Docker image: alpine:latest
Runner registered successfully.

​
Configure Docker executor settings

Edit the runner configuration to optimize image handling and security:
Bash
sudo nano /etc/gitlab-runner/config.toml
Locate the [[runners]] section for your newly registered runner. Add or modify the following under [runners.docker]:
None
[[runners]]
  name = "codesign-runner"
  url = "https://gitlab.com"
  token = "glrt-a8c3eFx9..."
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_cache = false
    volumes = ["/cache"]
    pull_policy = ["if-not-present"]
    allowed_images = ["*"]
    allowed_services = ["*"]
Key settings explained:
  • pull_policy = ["if-not-present"]: Reuses cached images; reduces pull time from 30s to <1s after first run
  • allowed_images = ["*"]: Permits any Docker image; lock this down in production (["openturns/*", "docker-registry.futurex.com/*"])
  • volumes = ["/cache"]: Persists build artifacts between jobs (optional but recommended)
Save and exit (Ctrl+X, Y, Enter).

​
Configure Futurex Docker registry authentication

Create a Docker config for the gitlab-runner user:
Bash
sudo -u gitlab-runner docker login docker-registry.futurex.com
Enter your registry credentials when prompted. This stores authentication in /home/gitlab-runner/.docker/config.json, which the runner automatically uses.

​
Restart the runner service

Apply configuration changes:
Bash
sudo gitlab-runner restart
Verify the runner is active:
Bash
sudo gitlab-runner status
Expected output: gitlab-runner: Service is running

​
Verify runner registration in GitLab UI

1
Go to your GitLab project.
2
SelectSettings > CI/CD.
3
Expand Runners.
4
Confirm your runner (codesign-runner) appears with a green status indicator.
5
Verify tags: mingw, codesign.
If the runner shows a red indicator, check /var/log/syslog for error messages:
sudo tail -f /var/log/syslog | grep gitlab-runner
Result:You now have a working GitLab Runner that can:
  • Pull images from Docker Hub (openturns/archlinux-mingw)
  • Pull images from the Futurex registry (docker-registry.futurex.com/kmes-cli:1.9.2-2)
  • Execute jobs tagged mingw (build stage) or codesign (sign stage)
Test it: Trigger a pipeline in your GitLab project. Jobs tagged mingw or codesign should start immediately (or within seconds).

​
Next steps

  • Add the signing pipeline: Configure .gitlab-ci.yml to use the mingw and codesign tags (covered in the next section).
  • Lock down image access: In production, replace allowed_images = ["*"] with an explicit allowlist. -Monitor runner logs: Watch for failures: sudo journalctl -u gitlab-runner -f