GitLab Runner is an agent that runs
GitLab CI/CD (Continues Integration/Continuous Deployment) jobs in a pipeline. It's heavily utilized in the world of DevOps to provision and configure infrastructure. The GitLab Runner can be installed as a binary on Linux, MacOS or Windows. It can also be installed as a container.
On this tutorial, I will walk through installing and configuring GitLab Runner as a container using a
Docker image on a RPI-4..yaay. I will make it very swift to get you started and won't feel a thing. I will not bore you with details, but if there are useful links for further study, I will definitely throw it in. The goal is to get you started with GitLab Runners and the rest is on you.
As a bonus, we will run our first job of building docker images and push them to
Docker hub. Enough reading, let's get our hands dirty, I mean our keyboards 😉
To lean more about GitLab Runners, refer to GitLab official documentation.
Note: Sensitive information will be pixilated or erased. This should not alter the quality of the tutorial.
If you don't have Docker installed on your RPI-4, you may refer to my Docker on Ubuntu 20.04 Raspberry Pi 4 tutorial.
1- Let's create a persistent Docker volume for the runner. On your RPI-4 terminal, run the following command:
docker volume create gitlab-runner-volume
Note: you can change the volume name
gitlab-runner-volume to any name of your chosen, but you should be consistent as we will use the volume name to bind the container to the RPI-4 local host.
2- Run the below commands to start GitLab Runner container:
docker run -d --name gitlab-runner --restart always --env TZ=US \ -v gitlab-runner-volume:/etc/gitlab-runner \ -v /var/run/docker.sock:/var/run/docker.sock \ gitlab/gitlab-runner:alpine
The only parameters you have the options to change are:
- the name flag,
- the volume name,
- the gitlab runner image,
- the env flag,
For more information about the installation process, here is the link GitLab's official documentation.
3- Capture the GitLab Runner token:
We do need to head to our
GitLab account and grab the runner's token. If you don't have a GitLab account, you can create one for free. Here is the link.
Now, we need to create a repository to host our project. From GitLab, let's click on create
New project. On the Create new project, select
create blank project. Then, give the project a name and click
Create project. In my case, I named my repo,
From the repository, let's click on settings, CI/CD and then Expand on the Runners section as shown below.
- Capture the token and save it on a note pad. We will need the token for the next step.
Enable shared runners for this project.
4- Register the GitLab Runner:
Replace the token place holder after
registration-token with the one from our note pad, and then run the following commands on your RPI-4 terminal:
docker run --rm -it -v gitlab-runner-volume:/etc/gitlab-runner gitlab/gitlab-runner:alpine register -n \ --url https://gitlab.com/ \ --registration-token GR1348941EDhyNWqfxPttukrGVKJd \ --executor docker \ --description "My Docker Runner" \ --docker-image "docker:20.10.12-dind-alpine3.15" \ --docker-privileged \ --docker-volumes "/certs/client"
If everything went smooth, you should not exhibit no errors as shown below.
To confirm that the GitLab Runner container is running, run the below Docker command:
docker ps -a
Alright, this is a great indication that we have successfully configured GitLab Runner on RPI-4. Now, we are ready to make some actions 💥
1- First of all, we need get a token from our
Docker hub account to avoid using account password. The token is to allow GitLab Runner to authenticate and push Docker images to our Docker hub repository. If you don't know what Docker hub is, it is the world's largest library for container images.
On Docker hub account settings, click on
New Access Token and generate a Read, Write, Delete token. Docker hub free account allows for one active token. Capture the token and save to a note pad.
2- From GitLab repo, which have we have created previously:
- Click on
Cloneand copy the
Clone with HTTPSlink.
- On your RPI-4 terminal and in a folder of your chosen, run the below command. This is where the repo will be saved locally:
git clone `your-Clone-with-HTTPS-link`
Note: the git clone command will prompt you to enter your GitLab credentials for authentication.
3- cd into the repo and either use a text editor or the terminal to edit the
.gitlab-ci.yml file. The file should only contain the following code. Be very careful with the indentation. Lastly, save the file:
image: docker:19.03.12 variables: IMAGE_NAME: "test:1.0.0" DOCKER_TLS_CERTDIR: "/certs" services: - docker:19.03.12-dind before_script: - docker info build image: stage: build script: - docker build -t $REGISTRY_USER/$IMAGE_NAME . - docker login -u $REGISTRY_USER -p $DOCKER_HUB_TOKEN - docker push $REGISTRY_USER/$IMAGE_NAME
4- We will create a simple
Dockerfile. The runner will use this Dockerfile to build a Docker image and push it to Docker hub. For right now, we will keep the Dockerfile VERY simple. Once the image is built from the Dockerfile, it will echo
With your preferred text editor or terminal, create and name a file Dockerfile without any extension. Then save it in the same local repo.
FROM alpine RUN echo "Hello World"
Note: In the local repo, we should have two files,
.gitlab-ci.yml. A README file might be there as well.
5- We will need to head back to GitLab repo to create two variables. On Settings, click on CI/CD, then expand
Variables. We will click on
Add variable to create two variables:
your Docker hub username NOT the email
the token which we generated from Docker hub
Note: the flags should be unchecked for simplicity for the two variables.
6- Now, we push the local repo to GitLab repo (remote repo) to start the GitLab Runner pipeline process. Yes, once the remote repo is updated, the runner will be triggered. Let's get back to our terminal on the RPI-4 and from within the local repo, run the following
git add -A git commit -am "first test" git push
If you head back to our GitLab repo and click on CI/CD under Pipelines, you would notice that the pipeline is
Moreover, if you click on the running status and you would be directed to the current stage, which is
Here, click on
build image, you shall see more details about the current build status. The goal is to see
Once you see Job succeeded and passed status in green, you can start doing your victory dance 👯 👯
If we head back to Docker hub account, we should see that our Docker image
test:1.0.0 has been successfully pushed to the repo.
By the end of this tutorial, we have successfully configured a GitLab Runner on a RPI-4, created a GitLab repo and registered GitLab Runner to it. Finally, we created a Hello World Docker image from a Dockerfile and had the runner building the Docker image and pushing it to our Docker hub account.
Now, off you go and the sky is the limit.