Dockerized GitLab CI: Setting Up and Connecting Your GitLab Runner
Continuing the series of Dockerized GitLab, in this post i’ll show you how to register a GitLab runner with your GitLab server for running your project pipelines to build, test and deploy your project.
In the first post, we set up a GitLab server using barebone docker commands. In the next post, we transitioned those barebone docker commands into a docker compose file for better usability and managing multiple containers easily.
GitLab Runner
With the completion of these 2 steps, we are good with our GitLab server by creating a repository, adding users, cloning and pushing changes to our respositories. But if we need to build our project or run some tests, we cannot do that as we don’t have any GitLab runner service.
GitLab runner is responsible for managing project pipelines while GitLab server is responsible for managing repositories, users and other configurations.
Create a Pipeline
Lets go ahead and create a respository i.e Build With Lal.
After adding the repository, go to the respository and then go to the Build settings for that respository.
Under the Build, click on Pipeline editor. Click on Configure pipeline
Paste the following basic pipeline script
build:
script:
- date # print current date
- cat /etc/os-release # print os version for Linux
After committing the pipeline changes, click on Pipelines under the Build.
And you should see that the pipeline is in Pending state and will remain in the Pending state forever until a GitLab runner comes in and pick it for processing.
Click on the Pending status button and then click on the build button on the next screen and you should see a message like this.
This job is stuck because you don't have any active runners that can run
this job. Go to project CI settingsThe message clearly says you don’t have any active runners . So we got a hint here that we need some runner which will actually run our pipeline.
If you click on the CI Settings as mentioned in that message, it will redirect you to the project runners page which look like this.
And here we don’t have any runners as mentioned by the message earlier.
Update Docker Compose File
Now before registering a GitLab runner, we need to make some minor updates to our docker-compose.yml file and it should look like this after adding external_url and changing GitLab server port inside GitLab container under environment variable GITLAB_OMNIBUS_CONFIG
version: '3.8'
services:
gitlab-server:
image: 'gitlab/gitlab-ce:latest'
container_name: gitlab-server
environment:
GITLAB_ROOT_EMAIL: "admin@buildwithlal.com"
GITLAB_ROOT_PASSWORD: "Abcd@0123456789"
# new changes
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://localhost:8000'
nginx['listen_port'] = 8000
ports:
- '8000:8000'
volumes:
- ./gitlab/config:/etc/gitlab
- ./gitlab/data:/var/opt/gitlabSo here we are adding a new environment variable GITLAB_OMNIBUS_CONFIG . Without external URL, some links will redirect to an invalid URL starting with the container ID. But since browser only knows fully qualified domain names or IPs, we need to add this external URL so GitLab server will set http://localhost:8000 as base URL for redirection everywhere.
After updating the docker-compose.yml file, hit CTRL+C and then run
docker compose up --build --force-recreateRegister GitLab Runner
Once the GitLab server is loaded with new changes, Click on the New project runner button under the project runners page and then fill out the form as shown below.
Click on Create runner button and it will redirect you to this screen
At this point, you have made entry for the runner in GitLab server but the actual runner is not registered yet as the message right above the Step 1 says:
GitLab Runner must be installed before you can register a runner.So this means we need to add another service called GitLab runner and once we have GitLab runner service, we’ll run the below command from Step 1 inside GitLab runner service and then our runner will be ready to run our pipelines. We’ll run below command once our GitLab runner container is ready.
gitlab-runner register --url http://localhost:8000 --token glrt-ydjvGwY6HqXrtBwz9MyhSo lets update our docker-compose.yml by adding GitLab runner container.
version: '3.8'
services:
gitlab-server:
image: 'gitlab/gitlab-ce:latest'
container_name: gitlab-server
environment:
GITLAB_ROOT_EMAIL: "admin@buildwithlal.com"
GITLAB_ROOT_PASSWORD: "Abcd@0123456789"
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://localhost:8000'
nginx['listen_port'] = 8000
ports:
- '8000:8000'
volumes:
- ./gitlab/config:/etc/gitlab
- ./gitlab/data:/var/opt/gitlab
# new changes for adding Gitlab Runner container
gitlab-runner:
image: gitlab/gitlab-runner:alpine
container_name: gitlab-runner
network_mode: 'host'We are adding a new service to the docker-compose.yml for GitLab runner which will use the docker image gitlab/gitlab-runner:alpine from the docker hub. We are setting network_mode to host for the GitLab runner container which will put the GitLab runner container on the host machine’s network so GitLab server can communicate with it through localhost instead of using its container name (container ID can change everytime we recreate containers).
After updating the docker-compose.yml file, hit CTRL+C to stop the running container and then run
docker compose up --build --force-recreateKeep watching for the health status of both Gitlab Server and Runner containers.
Once both are healthy, you can go back to the Runner page for your project here http://localhost:8000/root/build-with-lal/-/settings/ci_cd under
settings → CI/CD → Runners
build-with-lal in the URL is the repository name i’ve created earlier.
Click on the New project runner and follow the same steps as we followed earlier to generate command for registering GitLab runner which will look like this
gitlab-runner register --url http://localhost:8000 --token glrt-ydjvGwY6HqXrtBwz9MyhNow we need to execute this above command inside our GitLab runner container. So first login to the GitLab runner container using docker compose command
docker compose exec -it gitlab-runner /bin/bashNext run the command
gitlab-runner register --url http://localhost:8000 --token glrt-ydjvGwY6HqXrtBwz9Myh- When asking for the
GitLab instance URL, leave it as it is by hitting Enter unless your GitLab server and Runner are on different machines. - Enter your favourite name for the Runner.
- For now, we will select Shell as pipeline executor. We’ll work on the docker executor in our next post.
Once you fill out these details, you should be good and Runner registeration page should look like this.
and if you switch back to your project pipeline, the pipeline should have already run by showing as passed and printing these logs.
So first, its printing the current date on Shell and then its printing the OS details. Since we’ve selected Shell as pipeline executor when were registering our runner so the script will be run directly on the GitLab runner hosted OS which is Linux alpine as you can see in the docker-compose.yml.
...
gitlab-runner:
image: gitlab/gitlab-runner:alpine # alpine OS
...
This runner was dedicated to a specific project but if you want to register a global runner which could be available to all of the projects to execute any project’s pipeline, you can follow same steps here under your admin runners http://localhost:8000/admin/runners for registering a global runner.
Here you can also view all your registered runners and its status including project specific runners and global runners.
This was all about how to run a GitLab runner as a container service using docker compose and then register a pipeline runner inside that GitLab runner container to execute our project pipelines. The executor we used was Shell but these days since most of the projects are containerized and its widely used and adopted.
So in the next post, i am going to walk you through the process of registering a docker executor as a pipeline runner.
Source Code
Watch it on YouTube
Thank you for making it till the end 🎉
If this article helped you, make sure to:
