Blog Post

Azure Infrastructure Blog
3 MIN READ

Deploying a GitLab Runner on Azure: A Step-by-Step Guide

NamanNihal's avatar
NamanNihal
Icon for Microsoft rankMicrosoft
May 13, 2025

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

  1. Log in to the Azure Portal.
  2. 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)
  1. 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

  1. 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
  1. Test Docker with: docker run hello-world
  2. 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

  1. Download the GitLab Runner binary:
  2. Assign execution permissions:
  3. 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

  1. Navigate to runner section on your Gitlab to generate registration token (Gitlab -> Settings -> CI/CD -> Runners -> New Project Runner)
  2. 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

  1. After registration, restart the runner: sudo gitlab-runner restart
  2. 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:

  1. Run newgrp docker
  2. 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:

  1. Check runner status: sudo gitlab-runner status
  2. If inactive, restart the runner: sudo gitlab-runner restart
  3. 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!

Updated May 13, 2025
Version 1.0

2 Comments

  • Rishit's avatar
    Rishit
    Copper Contributor

    Great article, excellent overview of setting up a GitLab runner in Azure. Thanks for sharing your insights!

     

  • Ratnesh's avatar
    Ratnesh
    Copper Contributor

    This is a great overview of setting up an Azure GitLab runner.