If you're aiming to supercharge your CI/CD pipelines with a powerful self-hosted solution, deploying a GitLab Runner on an Azure Virtual Machine (VM) is an excellent choice.
This guide walks you through the entire process — from VM setup to running your first successful job.
Step 1: Create an Azure VM
- Log in to the Azure Portal.
- Create a new VM with the following settings:
-
- Image: Ubuntu 20.04 LTS (recommended)
- Authentication: SSH Public Key (generate a .pem file for secure access)
- Once created, note the public IP address.
Connect to the VM
From your terminal:
ssh -i "/path/to/your/key.pem" admin_name@<YOUR_VM_PUBLIC_IP>
Note: Make sure to replace the above command with path to .pem file and admin name which you would have given during VM deployment.
Step 2: Install Docker on the Azure VM
- Run the following commands to install Docker:
sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker #Enable Docker to start automatically on boot
sudo usermod -aG docker $USER
- Test Docker with: docker run hello-world
- A success message should appear. If you see permission denied, run: newgrp docker
Note: Log out and log back in (or restart the VM) for group changes to apply.
Step 3: Install GitLab Runner
- Download the GitLab Runner binary:
- Assign execution permissions:
- Install and start the runner as a service:
#Step1
sudo chmod +x /usr/local/bin/gitlab-runner
#Step2
sudo curl -L --output /usr/local/bin/gitlab-runner \
https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
#Step3
sudo gitlab-runner install --user=azureuser
sudo gitlab-runner start
sudo systemctl enable gitlab-runner #Enable GitLab Runner to start automatically on boot
Step 4: Register the GitLab Runner
- Navigate to runner section on your Gitlab to generate registration token (Gitlab -> Settings -> CI/CD -> Runners -> New Project Runner)
- On your Azure VM, run:
sudo gitlab-runner register \
--url https://gitlab.com/ \
--registration-token <YOUR_TOKEN> \
--executor docker \
--docker-image Ubuntu:22.04 \
--description "Azure VM Runner" \
--tag-list "gitlab-runner-vm" \
--non-interactive
Note: Replace the registration toke, description, tag-list as required
- After registration, restart the runner: sudo gitlab-runner restart
- Verify the runner’s status with: sudo gitlab-runner list
Your runner should appear in the list.
If runner does not appear, make sure to follow step 4 as described.
Step 5: Add Runner Tags to Your Pipeline
In .gitlab-ci.yml
default:
tags:
- gitlab-runner-vm
Step 6: Verify Pipeline Execution
Create a simple job to test the runner:
test-runner:
tags:
- gitlab-runner-vm
script:
- echo "Runner is working!"
Troubleshooting Common Issues
Permission Denied (Docker Error)
Error:
docker: permission denied while trying to connect to the Docker daemon socket
Solution:
- Run newgrp docker
- If unresolved, restart Docker: sudo systemctl restart docker
No Active Runners Online
Error:
This job is stuck because there are no active runners online.
Solution:
- Check runner status: sudo gitlab-runner status
- If inactive, restart the runner: sudo gitlab-runner restart
- Ensure your runner tag in the pipelines matches the one you provided while creating runner for project
Final Tips
Always restart the runner after making configuration changes: sudo gitlab-runner restart
Remember to periodically check the runner’s status and update its configuration as needed to keep it running smoothly.
Happy coding and enjoy the enhanced capabilities of your new GitLab Runner setup!