Install GitLab Runner on Red Hat OpenShift

Version history

You can install the GitLab Runner on Red Hat OpenShift v4 and later using the GitLab Runner Operator available from the beta channel of OperatorHub embedded in OpenShift’s web console. Once installed, you can run your GitLab CI/CD jobs using the newly deployed GitLab Runner instance. Each CI/CD job will run in a separate pod.

Prerequisites

  • OpenShift 4.x cluster with administrator privileges
  • GitLab Runner registration token

Install the OpenShift Operator

First you must install the OpenShift Operator.

  1. Open the OpenShift UI and log in as a user with administrator privileges.
  2. In the left pane, click Operators, then OperatorHub.
  3. In the main pane, below All Items, search for the keyword GitLab Runner.

    GitLab Operator

  4. To install, click the GitLab Runner Operator.
  5. On the GitLab Runner Operator summary page, click Install.
  6. On the Install Operator page:
    1. Under Update Channel, select stable.
    2. Under Installed Namespace, select the desired namespace and click Install.

    GitLab Operator Install Page

On the Installed Operators page, when the GitLab Operator is ready, the status changes to Succeeded.

GitLab Operator Install Status

Install GitLab Runner

Now install GitLab Runner. The version you’re installing is tagged as the latest in the Red Hat Ecosystem Catalog container list.

  1. Obtain a token that you’ll use to register the runner:
    • For a shared runner, have an administrator go to the GitLab Admin Area and click Overview > Runners.
    • For a group runner, go to Settings > CI/CD and expand the Runners section.
    • For a project-specific runner, go to Settings > CI/CD and expand the Runners section.
  2. Under Use the following registration token during setup:, copy the token.
  3. Open an OpenShift console and switch to the project namespace:

    oc project "PROJECT NAMESPACE"
    
  4. Create the secret file with your GitLab project’s runner token:

    cat > gitlab-runner-secret.yml << EOF
    apiVersion: v1
    kind: Secret
    metadata:
      name: gitlab-runner-secret
    type: Opaque
    stringData:
      runner-registration-token: REPLACE_ME # your project runner secret
    EOF
    
  5. Create the secret in your cluster by running:

    oc apply -f gitlab-runner-secret.yml
    
  6. Create the Custom Resource Definition (CRD) file and include the following information. The tags value must be openshift for the job to run.

    cat > gitlab-runner.yml << EOF
    apiVersion: apps.gitlab.com/v1beta2
    kind: Runner
    metadata:
      name: gitlab-runner
    spec:
      gitlabUrl: https://gitlab.example.com
      buildImage: alpine
      token: gitlab-runner-secret
      tags: openshift
    EOF
    
  7. Now apply the CRD file by running the command:

    oc apply -f gitlab-runner.yml
    
  8. Confirm that GitLab Runner is installed by running:

    oc get runners
    NAME             AGE
    gitlab-runner    5m
    
  9. The runner pod should also be visible:

    oc get pods
    NAME                             READY   STATUS    RESTARTS   AGE
    gitlab-runner-bf9894bdb-wplxn    1/1     Running   0          5m
    

Install other versions of GitLab Runner

If you do not want to use the version of GitLab Runner Operator that’s available in the RedHat OperatorHub, you can install a different version.

To find out the official currently-available Operator versions, view the tags in the gitlab-runner-operator repository. To find out which version of GitLab Runner the Operator is running, view the APP_VERSION variable in the Makefile of the commit/tag you are interested in, for example, https://gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/-/blob/v1.0.0/Makefile.

To install a specific version, create this catalogsource.yaml file and replace <VERSION> with a tag or a specific commit:

note
When using an image for a specific commit, the tag format is v0.0.1-<COMMIT>. For example: registry.gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/gitlab-runner-operator-catalog-source:v0.0.1-f5a798af.
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: gitlab-runner-catalog
  namespace: openshift-marketplace
spec:
  sourceType: grpc
  image: registry.gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/gitlab-runner-operator-catalog-source:<VERSION>
  displayName: GitLab Runner Operators
  publisher: GitLab Community

Create the CatalogSource with:

oc apply -f catalogsource.yaml

In a minute the new Runner should show up in the OpenShift cluster’s OperatorHub section.

Configuration

To configure GitLab Runner in OpenShift, see the Configuring GitLab Runner on OpenShift page.