Ensure Your CI/CD Pipelines with a Self-Hosted GitLab Runner 🚀 with Docker 🐳

Why would I want to have my own GitLab runner?

There are several reasons why having your own GitLab runner is beneficial compared to what GitLab offers on its own or with the free plan:

  1. Reduce build and deployment times.

    Having our own runner is equivalent to using the machine of our choice. It's essential to consider that GitLab ultimately provides machines used by multiple users with their limitations. By having our dedicated runners, we know that those runners are only working for us.

  2. Run CI/CD processes on your own machine.

    We often think that when we have a CI/CD pipeline, it should run on a separate server, but it doesn't have to be that way. If we set up Docker on our machine, as we'll see below, it will work exactly the same as if we had a dedicated server for it.

  3. Budget considerations.

    GitLab's free plan offers a limited number of minutes, which may not be sufficient. With our own runner, we can run CI/CD as many times as needed without the limitations of the free plan. This, combined with point 2, can potentially save money.

  4. When chaos reigns.

    It's frustrating when deployments fail simply because the CI/CD environment is down or there are no available runners. By running the runner on our machine, we can overcome this issue.


To follow this guide, the essential requirement is to have Docker installed on the machine where the runner will be launched. It's also necessary to have maintainer permissions in the repository where the content to apply our CI/CD process with the runner is located.

Setting up our runner with containers

For this tutorial, I'll use Docker Compose because it seems more convenient to me, but you could also use docker run if you prefer.


version: "3.5"
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
      - ./gitlab-runner:/etc/gitlab-runner
    restart: always

As we can see in the above docker-compose file, we share the Docker .sock to allow the runner to launch containers. Also, in the same folder as the docker-compose.yml file, I've created a folder named gitlab-runner containing a config.toml file. In this file, we will configure the details of our runner. Here's a basic example:


concurrent = 4
check_interval = 0

  session_timeout = 1800

  name = "My GitLab self-hosted runner"
  url = "https://gitlab.com/"
  token = "xxxxx"
  executor = "docker"
    tls_verify = false
    image = "docker:stable"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
    shm_size = 0

Important: To generate our token, we need to go to our repository in Settings > CI/CD > Runners. By expanding, we will find a New Project Runner button.

Follow the steps provided by GitLab. It's crucial that, if we want it to apply to all jobs, we select the Run untagged jobs checkbox. When pressing Create runner, it will provide the corresponding token.

With all this, our runner would be ready to start building our applications. Remember that, obviously, you'll need to define the build process in the gitlab-ci.yml file in the corresponding repository.

The URL will depend on whether the repository is hosted on gitlab.com or if your company has a self-hosted GitLab instance, in which case, you'll need to change the parameter indicating the URL.

How can I assign a runner to a group?

The process is very similar to adding it to a specific repository.

  1. Click on the group, go to Settings > CI/CD > Runners, and make sure the option Enable instance runners for this group is enabled.

  2. In the left panel, look for Deploy > Runners. In the top right, you'll see a New group runner button. Follow the steps, and at the end, it will provide a token, just like when adding the runner to a specific repository. Add it to your configuration, and you'll have it ready.