Deploying a GitHub Actions Self-hosted Runner on Azure: A Step-by-Step Guide

In this guide, we’ll walk through deploying a GitHub Actions self-hosted runner on an Azure VM, step by step.

Pre-requisites

Before you begin, ensure you have:

1. A GitHub repository or organization
2. Access to the Azure Portal
3. An SSH client (e.g., Windows Terminal, macOS Terminal)
4. Basic familiarity with Linux (Ubuntu)

Step 1: Provisioning an Azure VM

1. Go to the Azure Portal
2. Search for Virtual Machines → click + Create
3. Fill in the Basics tab:
   • VM Name: gh-runner-vm
   • Region: East US (or your preferred region)
   • Image: Ubuntu 22.04 LTS
   • Size: Standard B1s
   • Authentication: SSH Public Key
   • Username: azureuser
4. In the Networking tab: Allow SSH (port 22)
5. Click Review + Create and deploy the VM

Step 2: Connect to the VM

Once deployed:

1. Go to Virtual Machines → select your VM
2. Click Connect → SSH
3. Copy the SSH command and run it in your terminal:

ssh -i "/path/to/your/key.pem" admin_name@<YOUR_VM_PUBLIC_IP>

Step 3: Download and Configure GitHub Runner

Install dependencies:

sudo apt update && sudo apt install -y curl tar jq

Download the GitHub Runner:

1. Go to your GitHub repo → Settings → Actions → Runners → New self-hosted runner
2. Select:
   • OS: Linux
   • Architecture: x64
3. Run the provided commands, e.g.:

mkdir actions-runner && cd actions-runner curl -o actions-runner-linux-x64-2.316.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.316.1/actions-runner-linux-x64-2.316.1.tar.gz tar xzf ./actions-runner-linux-x64-2.316.1.tar.gz

Configure the runner:

Note: Replace the placeholders below with actual values

./config.sh --url https://github.com/<your-username>/<your-repo> --token <generated-token>

Follow the prompts for runner name, work folder, and labels.

Step 4: Install and Start Runner as a Service

sudo ./svc.sh install sudo ./svc.sh start sudo ./svc.sh status

This ensures the runner starts automatically on reboot.

Step 5: Validate the Runner

Go to your GitHub repo → Settings → Actions → Runners

You should see your runner listed with a green dot 

Step 6: Run GitHub Actions Workflows

Create a workflow file .github/workflows/test.yml:

name: Test Self-Hosted Runner

on: [push]

jobs:
  test:
    runs-on: self-hosted
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Run a script
        run: echo "Hello from GitHub self-hosted runner!"

Push it to your repo and watch it run on your Azure VM 

Bonus: Auto-start and Cleanup

Auto-start is handled by:

sudo ./svc.sh install

To remove the runner:

sudo ./svc.sh stop sudo ./svc.sh uninstall ./config.sh remove

Docker permissions (if needed):

sudo usermod -aG docker azureuser sudo systemctl restart docker

Restart runner service:

sudo systemctl restart actions.runner.azureuser.actions-runner.service

By setting up a self-hosted GitHub Actions runner on Azure, you unlock greater flexibility, performance, and control over your CI/CD workflows — empowering you to build, test, and deploy with confidence in your own cloud environment.