In this guide, we’ll walk through deploying a GitHub Actions self-hosted runner on an Azure VM, step by step.
Pre-requisitesBefore you begin, ensure you he:
A GitHub repository or organization Access to the Azure Portal An SSH client (e.g., Windows Terminal, macOS Terminal) Basic familiarity with Linux (Ubuntu) Step 1: Provisioning an Azure VM Go to the Azure Portal Search for Virtual Machines → click + Create 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 In the Networking tab: Allow SSH (port 22) Click Review + Create and deploy the VM Step 2: Connect to the VMOnce deployed:
Go to Virtual Machines → select your VM Click Connect → SSH Copy the SSH command and run it in your terminal: ssh -i "/path/to/your/key.pem" admin_name@ Step 3: Download and Configure GitHub Runner Install dependencies: sudo apt update && sudo apt install -y curl tar jq Download the GitHub Runner: Go to your GitHub repo → Settings → Actions → Runners → New self-hosted runner Select: OS: Linux Architecture: x64 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// --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 statusThis ensures the runner starts automatically on reboot.
Step 5: Validate the RunnerGo to your GitHub repo → Settings → Actions → Runners
You should see your runner listed with a green dot
Step 6: Run GitHub Actions WorkflowsCreate 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.serviceBy 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.