GitLab is a DevOps automation platform that allows for version control, collaboration, automation of engineering processes through CI/CD pipelines, and more. Among their offerings, GitLab allows users to connect to a Kubernetes cluster which means it can be used to set up pipelines for automatic deployments to different environments as well as managing advanced deployment strategies such as canary releases.

This tutorial provides an overview of how users can connect their Kubernetes cluster to GitLab. In the next guides, we will see how to create a GitLab pipeline that deploys new resources to your Kubernetes cluster.


Before you begin, please make sure you:

  • Have a Civo account set-up with a running cluster. Have a look at this guide on how to set up your first Civo Kubernetes cluster.

  • Have a GitLab account -- the free trial account will be enough for this tutorial

  • Have kubectl installed

Civo Kubernetes Dashboard

Lastly, you will need access to your cluster that is running on Civo. Download the Kubeconfig file from the Civo UI and connect kubectl to your cluster.

This can be done by exporting the Kubeconfig as an environment variable. In the directory with your Kubeconfig run:

export KUBECONFIG=$(pwd)/civo-example-kubeconfig

Make sure to validate the access to your cluster.

kubectl get nodes

This should show the nodes running in your cluster that match the information in your account.

GitLab Kubernetes

GitLab will require several pieces of information on your Kubernetes cluster to connect. Let’s navigate to the Settings page for this. Open your GitLab account and select “Kubernetes” on the left sidebar. To find the setting, you have to go to “groups” or replace the username with yours in the following URL:[username]/-/clusters

GitLab sidebar

Next, select “Integrate Kubernetes with a cluster certificate”. This will provide you with two options. Either you can create a new cluster with other cloud providers or you can connect to an existing Kubernetes cluster. Let’s open the second tab to add an existing cluster. The below screenshot displays the UI that you should be seeing at this point:

Adding cluster information to GitLab

Perfect! We can now provide our cluster credentials to GitLab.

Provide Credentials

  1. You can provide GitLab any name that you wish to give the cluster. However, to avoid confusion, we are going to provide GitLab with the same cluster name as the name that we have specified in Civo. In our case, this will be “cli-example”.

  2. Next, we have to specify the cluster scope. We are going to keep it simple and give GitLab access to our entire cluster. However, you might want to restrict access to specific namespaces. Restricting access to specific namespaces is better practice since that will provide you with more control over your Kubernetes cluster operating by “least-privileges”.

  3. Now it is going to be fun. We need the cluster API URL to our cluster. The Civo UI makes it really easy to find the URL, please navigate to Dashboard and access the Kubernetes cluster that you want to connect to GitLab:

Civo cluster information screen

Alternatively, you can use kubectl to find the URL. To do so, run the following command in your terminal (assuming you are connected to your Civo Kubernetes cluster)

kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}'

Once you have the URL, copy-paste it into the GitLab UI.

  1. Next, we need the PEM certificate. Make sure you are connected to your Civo Kubernetes cluster through kubectl and run the following command:
echo $(kubectl get secret -o go-template='{{index .data "ca.crt" }}' $(kubectl get sa default -o go-template="{{range .secrets}}{{.name}}{{end}}")) | base64 -d

This will provide you with the certificate for your cluster. Make sure to copy the entire terminal output, including the header and ending:

  1. Now we need to create a Service Account for GitLab. Save the following YAML file:
apiVersion: v1
kind: ServiceAccount
  name: gitlab
  namespace: kube-system
kind: ClusterRoleBinding
  name: gitlab-admin
  kind: ClusterRole
  name: cluster-admin
  - kind: ServiceAccount
    name: gitlab
    namespace: kube-system

In our case, we called the file gitlab-service-account.yaml. Now we can apply the resource to your cluster:

kubectl apply -f gitlab-service-account.yaml

This will allow us to view the access token for our GitLab ServiceAccount:

kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}')

Copy the token and paste it into the GitLab UI.

Screen on GitLab to add your service token

Lastly, we are going to leave all the boxes ticked. Now you can click “add Kubernetes cluster” to finish connecting your Civo Kubernetes Cluster to GitLab.

GitLab Kubernetes Cluster integration screen

What’s next?

Our goal is to automate as much of our manual processes as possible. One way to do this is through CI/CD pipelines. If you are interested in some use cases and examples, have a look at the following guides:

Additionally, we highly encourage you to create your own guides. Just submit those through the content section in the Civo Dashboard of your account. We look forward to seeing all the amazing use cases that you create. Make sure you tell us on the Civo community Slack!