Win $20,000. Help build the future of education. Answer the call. Learn more

Use GitLab runners on Kubernetes

In a new generation of software development, also known as Cloud Native, it simply requires pipelines to be successful. You need to have a comfort blanket for your development, which is the main why CD/CI are so prevalent in our industry now. There are multiple ways to create a standarized pipelne and luckily there is already some good starting points to get yourself bootstrapped.


This tutorial’s purpose is to teach you how to connect your IBM Cloud Kubernetes Service cluster to a hosted GitLab instance so that you can leverage your own infrastructure for continuous integration and continuous deployment.

Much of this tutorial is influenced by the official documentation from GitLab.


Before you begin going through the steps in this tutorial, you will need the following:

  1. A Kubernetes cluster on the IBM Cloud.

    • And an IP that your GitLab instance can reach.
  2. An IBM Cloud CLI installed and configured on your work station.


  1. Authenticate with the IBM Cloud CLI so that you can connect to your Kubernetes cluster.

     ibmcloud login # with --sso if you need to use single sign on
     ibmcloud cs region-set us-south # The region you have your cluster in
     ibmcloud cs cluster-config YOURCLUSTERNAME # you will need to run the export KUBECONFIG command
     kubectl get nodes # a sanity check to make sure you can authenticate with your Kubernetes cluster
  2. Create a directory to work inside of it, as this will be used later on. It’s a place to create some files and have a place to store them in case you need to reference them at a later date.

     mkdir gitlab-runner
     cd gitlab-runner
  3. Add the helm repo from GitLab, this will make sure you have the most up to date charts from Gitlab.

     helm repo add gitlab
  4. Initialize helm on both your local machine and in your Kubernetes cluster.

     helm init
  5. Create a values.yaml for your configuration of gitlab-runner. The full values.yml is here.

     vi values.yaml
  6. The only two settings you have to edit in the values.yaml are the following:

    • gitlabUrl – The GitLab Server URL (with protocol) to register the runner against.
    • runnerRegistrationToken – The Registration Token for adding new Runners to the GitLab Server. This must be retrieved from your GitLab Instance. See the GitLab Runner Documentation for more information.
  7. After the configuration is complete, run the following command with a NAMESPACE that won’t step on another project. Using something like gitlab-runners as the namespace will isolate the pods in your Kubernetes cluster.

     helm install --namespace NAMESPACE --name gitlab-runner -f values.yaml gitlab/gitlab-runner
  8. You should now be able to see your runner in the admin/runners URL on your GitLab instance. This means you successfully ran GitLab on your Kubernetes instance to talk to your GitLab instance. You can now run your tests through this gitlab-runner in your on environment on your instances.


To uninstall the GitLab Runner Chart, run the following:

helm delete --namespace NAMESPACE RELEASE-NAME

Next steps

You just completed the steps to connecting a Kubernetes cluster to GitLab! Wondering what to try out next? Try out the code pattern, Run GitLab on Kubernetes or our other code patterns! For more on CI/CD, you might be interested in learning how to define a simple CD pipeline with Knative.