A Singapore Government Agency Website

Set up agency-hosted GitLab runners

This topic is for SHIP-HATS users who intend to set up a agency-hosted GitLab runner.

This registration process is only supported in GitLab Runner 15.10 or later. This registration process is not supported in GitLab Runner 15.9 or earlier and only available as an experimental feature in GitLab Runner 15.10 and 15.11. You should upgrade to GitLab Runner 16.0 or later to use a stable version of this registration process. For more details, refer to: https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html.

Overview of agency-hosted runner setup

Following are the steps involved when you set up agency-hosted runner.

Step Task
1 Ensure prerequisites
2 Retrieve runner token
3 Install and register runner

Step 1: Ensure prerequisites

  1. Ensure you have access to your hosted environment or virtual machine (VM).
  2. Establish network connectivity for private network link via AWS VPCE for AWS or Azure Private Link for Azure.
  3. Confirm that your accounts are on the GCC platform (GCC 1.0 or GCC 2.0).

Step 2: Retrieve runner token

Depending on your use case, you can configure either a group runner or project runner.

  • Group runner: This runner is shared among all projects within the group.

  • Project runner: This runner is dedicated to a single project.

  1. Go to GitLab and from the left sidebar, select Search or go to and find your group.

  2. Select Build > Runners.

  3. Select New group runner.

    new-group-runner

  4. Select your preferred runner tags and additional configurations to generate the project runner authentication token.

  5. In the Tags section, in the Tags field, enter the job tags to specify jobs the runner can run.

  6. [Optional] In the Configuration section, add additional configurations.

  7. Select Create runner.

    create-runner

  8. Copy the registration token displayed and proceed to install the runner.

  1. Go to GitLab and from the left sidebar, select Search or go to and find your project.

  2. Select Settings > CI/CD.

  3. Expand the Runners section and select New project runner.

    project-runner

  4. In the Tags section, in the Tags field, enter the job tags to specify jobs the runner can run.

  5. [Optional] In the Configuration section, add additional configurations.

    project-runner

  6. Select Create runner.

  7. Copy the registration token displayed and proceed to install the runner.

Step 3: Install and register runner

You can install runner in the following environments based on your setup:

  • Linux(amd64)
  • macOS (amd64)
  • Windows (amd64)
  • Docker
  • Kubernetes

Follow the below instructions to:

  • Download the binary file
  • Install the binary file
  • Register the runner

  1. Download the binary for your system using:

    sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

  2. Give it permission to execute using:

    sudo chmod +x /usr/local/bin/gitlab-runner

  3. Create a GitLab Runner user using:

    sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

  4. Install and run as a service using:

    sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
    sudo gitlab-runner start

  5. To register the runner, in the following command, replace the placeholder XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual registration token retrieved in Step 2: Retrieve runner token:

    sudo gitlab-runner register --url https://sgts.gitlab-dedicated.com/ --registration-token XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    If you encounter a net/http: TLS handshake timeout error during registration, follow the steps below to resolve it:
    A. Open PowerShell with administrative privileges.
    B. Execute the following commands to force PowerShell to use TLS 1.2:
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Invoke-WebRequest -Uri https://sgts.gitlab-dedicated.com -UseBasicParsing
    C. Retry the runner registration command in step 5.

  1. Download the binary for your system using:

    sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64

  2. Give it permission to execute using:

    sudo chmod +x /usr/local/bin/gitlab-runner

Execute the rest of the commands as the user who will run the runner.

  1. To register the runner, in the following command, replace the placeholder XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual registration token retrieved in Step 2: Retrieve runner token:

    gitlab-runner register  --url https://sgts.gitlab-dedicated.com  --token glrt-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    If you encounter a net/http: TLS handshake timeout error during registration, follow the steps below to resolve it:
    A. Open PowerShell with administrative privileges.
    B. Execute the following commands to force PowerShell to use TLS 1.2:
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Invoke-WebRequest -Uri https://sgts.gitlab-dedicated.com -UseBasicParsing
    C. Retry the runner registration command in step 3.

  2. Run the following commands:

    cd ~
gitlab-runner install
gitlab-runner start

  1. Run PowerShell. For more details, on how to start Windows PowerShell with administrative privileges, refer to the Microsoft Documentation.

  2. Choose a location on your system to create a new folder. For example, to create a folder named GitLab-Runner in the C: drive, run the following command in PowerShell to create the folder:

    New-Item -Path 'C:\GitLab-Runner' -ItemType Directory

  3. Navigate to the newly created folder by running the following command:

    cd 'C:\GitLab-Runner'

  4. Download the binary file using the following command:

    Invoke-WebRequest -Uri "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe" -OutFile "gitlab-runner.exe"

  5. To register the runner, in the following command, replace the placeholder XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with your actual registration token retrieved in Step 2: Retrieve runner token:

    ./gitlab-runner.exe register --url https://sgts.gitlab-dedicated.com/ --token glrt-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    If you encounter a net/http: TLS handshake timeout error during registration, follow the steps below to resolve it:
    A. Open PowerShell with administrative privileges.
    B. Execute the following commands to force PowerShell to use TLS 1.2:
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Invoke-WebRequest -Uri https://sgts.gitlab-dedicated.com -UseBasicParsing
    C. Retry the runner registration command in step 5.

  6. Run the following commands:

    .\gitlab-runner.exe install
.\gitlab-runner.exe start

To install Runner in a container, follow the instructions described in the GitLab documentation.

To install Runner in Kubernetes, follow the instructions described in the GitLab documentation.

PREVIOUS
Example setup for agency-hosted runners
NEXT
Overview of DORA metrics
Chat with me!
Bot Launcher