Self-Hosted GitHub Runners

Self-hosted GitHub runners can significantly reduce CI/CD workflow execution time, especially for build jobs. By caching generic images, build images, and artifacts, build performance can be dramatically improved.

Benefits of Self-Hosted Runners

Faster Builds

Cache images and artifacts for significantly faster build times

Resource Control

Control hardware specs and optimize for your workload

Cost Efficiency

Reduce GitHub Actions minutes usage for large projects

Runner Registration Scope

GitHub runners can be registered at two levels:

Organization level - Accessible to all repositories in the organization
Repository level - Dedicated to a single repository

Registration URLs

Organization
Repository

Navigate to:

https://github.com/organizations/{organization}/settings/actions/runners/new

Navigate to:

https://github.com/{organization}/{repository}/settings/actions/runners

Setup Methods

You can set up self-hosted runners using two approaches:

Azure VM Template

Quick automated setup using Microsoft’s template

Manual Setup

Full control over runner configuration and dependencies

Method 1: Azure VM Template

The fastest way to create self-hosted runners is using the Azure VM template.

Access Template

Navigate to https://aka.ms/getbuildagent in a new tab.

Configure VM Settings

Enter the following information:

Resource Group name - Azure resource group for the VM
Region - Azure region for deployment
VM Name - Name for your virtual machine
Admin Password - Administrator password for VM access
Number of agents - How many runners to create on the VM

Configure Runner Settings

From the GitHub “Create Self-Hosted Runner” page, copy:

Token - Registration token from GitHub
Organization URL - Your GitHub organization URL
Agent URL - GitHub Actions runner download URL
Labels - Set to self-hosted

Deploy

Select Review and Create, review the configuration, then choose Create.

Verify Registration

Wait for Azure VM creation to complete, then verify the runners appear as registered and ready on GitHub.

The Azure template automatically installs all required dependencies including Docker, PowerShell, Git, and development tools.

Method 2: Manual Setup

For more control over the runner environment, you can set up runners manually.

Choose Configuration

On the GitHub runner registration page, select:

Runner Image: Windows
Architecture: x64

Follow Installation Steps

Follow the provided instructions to download and configure the runner on your machine.

Install Required Software

Ensure the following software is installed:

Required Dependencies

Docker
PowerShell Tools
Development Tools
NuGet

Install Docker Engine using this script.

Set the EnvScope to Machine if installing Docker with a different user than the one running the agents.

Install the Azure PowerShell module:

Install-Module az -force

Install using Chocolatey:

# Install Chocolatey first
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# Install Git
choco install git --force --params "/NoAutoCrlf"

# Install other tools
choco install 7zip -y
choco install gh -y
choco install pwsh -y
choco install vcredist140 -y
choco install dotnet -y
choco install dotnet-sdk -y

Add nuget.org as a dotnet source:

dotnet nuget add source https://api.nuget.org/v3/index.json --name nuget.org

Complete Software List

Software	Purpose	Installation Method
Docker Engine	Container runtime	PowerShell script
Azure PowerShell Module	Azure integration	`Install-Module az -force`
Git	Version control	`choco install git --force --params "/NoAutoCrlf"`
7-Zip	Archive extraction	`choco install 7zip`
GitHub CLI	GitHub operations	`choco install gh`
PowerShell 7.4.1+	Scripting runtime	`choco install pwsh -y`
Visual C++ Redistributable	Runtime libraries	`choco install vcredist140 -y`
.NET Runtime	Application runtime	`choco install dotnet -y`
.NET SDK	Development SDK	`choco install dotnet-sdk -y`

If the Deploy Reference Documentation job fails with errors, verify your Git installation configuration. See this issue for details.

Configure Repository Access

Once your runners are set up, configure your repository to use them.

Configure Runner Group

On the GitHub runners list, select the Default runner group and allow public repositories if your repository is public.

Update AL-Go Settings

Edit your repository settings file at .github/AL-Go-Settings.json and set the gitHubRunner property:

{
  "gitHubRunner": "self-hosted"
}

You can use additional tags like "self-hosted, Windows" to target specific runner types if you have multiple self-hosted runners with different operating systems.

Test and Verify

Commit the settings change and monitor your workflows. You should see:

Performance improvements on the second run (after cache is populated)
Runners picking up workflow jobs
Active status on the runner in GitHub settings

Understanding Runner Settings

AL-Go provides two settings to control runner selection:

gitHubRunner vs. runs-on

gitHubRunner
runs-on

Used for: Build and test jobs requiring:

High memory and CPU
Docker container support
Longer execution times

{
  "gitHubRunner": "self-hosted"
}

Build jobs benefit most from self-hosted runners due to caching capabilities.

Used for: Lightweight jobs like:

Initialization
Post-processing
Deployment coordination
Artifact management

{
  "runs-on": "ubuntu-latest"
}

We do not recommend using self-hosted runners for runs-on jobs. Many of these jobs run in parallel and use minimal resources. GitHub-hosted runners (especially ubuntu-latest) are faster and more cost-effective for these tasks.

Performance Optimization

Runner Capacity Planning

Based on real-world testing:

Over-allocation Risk

Running 5+ concurrent builds on a single VM causes:

50% slower individual build times
High CPU contention
Memory pressure

Optimal Configuration

Running 4 concurrent builds provides:

Similar performance to single build
Good resource utilization
Minimal queuing

Performance Tips

Disable Real-Time Protection

Turning off Windows Defender real-time protection on self-hosted runners can improve build performance by approximately 25%.

Only disable antivirus protection if your runners are in a secure, isolated network environment.

Right-Size Runner Count

Monitor CPU and memory usage to determine optimal runner count:

Start with 4 runners per VM
Monitor performance during concurrent builds
Adjust based on actual workload

Use SSD Storage

Docker image caching benefits significantly from fast storage:

Use SSD or NVMe storage for runner workspace
Allocate sufficient disk space for image cache

Performance Metrics

Typical improvements with self-hosted runners:

Metric	GitHub-Hosted	Self-Hosted (First Run)	Self-Hosted (Cached)
Build Time	Baseline	Similar to baseline	50-70% faster
Image Download	Every run	First run only	Cached
Artifact Access	Remote	Remote	Local cache available

Monitoring Runners

Track runner performance and activity:

View Active Jobs

Click on a runner in GitHub settings to see:

Current job being executed
Job duration
Workflow name and run ID

Monitor Queue

Check for queued workflows when all runners are busy:

Workflows will wait for available runners
Consider adding more runners if queuing is frequent

Check Resource Usage

Connect to the runner VM to monitor:

CPU utilization
Memory usage
Disk I/O
Network activity

Runners show as “Idle” when not executing jobs and “Active” when running workflows. A green status indicator confirms the runner is online and available.

Troubleshooting

Common Issues

Runners not picking up jobs

Verify:

Runner is online and shows “Idle” status
Repository has access to the runner group
gitHubRunner setting matches runner labels
Runner has sufficient disk space

Slow build performance

Check:

Number of concurrent builds vs. runner capacity
CPU and memory usage during builds
Antivirus real-time scanning
Disk I/O performance

Runner offline/disconnected

Investigate:

Runner service status on the VM
Network connectivity to GitHub
VM resource availability
Registration token expiration

Security Considerations

Important security notes for self-hosted runners:

Do not use self-hosted runners with public repositories unless they are in an isolated environment
Self-hosted runners can execute arbitrary code from pull requests
Use GitHub’s security features to restrict runner access
Regularly update runner software and dependencies
Monitor runner activity for suspicious behavior

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

Benefits of Self-Hosted Runners

Faster Builds

Resource Control

Cost Efficiency

Runner Registration Scope

Registration URLs

Setup Methods

Azure VM Template

Manual Setup

Method 1: Azure VM Template

Method 2: Manual Setup

Required Dependencies

Complete Software List

Configure Repository Access

Understanding Runner Settings

gitHubRunner vs. runs-on

Performance Optimization

Runner Capacity Planning

Over-allocation Risk

Optimal Configuration

Performance Tips

Performance Metrics

Monitoring Runners

Troubleshooting

Common Issues

Security Considerations

Next Steps

Azure KeyVault Integration

Enable Telemetry

Build docs developers (and LLMs) love

Getting Started

Setup & Configuration

Core Workflows

Development

Deployment

AppSource Publishing

Advanced Topics

Migration

​Benefits of Self-Hosted Runners

Faster Builds

Resource Control

Cost Efficiency

​Runner Registration Scope

​Registration URLs

​Setup Methods

Azure VM Template

Manual Setup

​Method 1: Azure VM Template

​Method 2: Manual Setup

​Required Dependencies

​Complete Software List

​Configure Repository Access

​Understanding Runner Settings

​gitHubRunner vs. runs-on

​Performance Optimization

​Runner Capacity Planning

Over-allocation Risk

Optimal Configuration

​Performance Tips

​Performance Metrics

​Monitoring Runners

​Troubleshooting

​Common Issues

​Security Considerations

​Next Steps

Azure KeyVault Integration

Enable Telemetry

Build docs developers (and LLMs) love

Benefits of Self-Hosted Runners

Runner Registration Scope

Registration URLs

Setup Methods

Method 1: Azure VM Template

Method 2: Manual Setup

Required Dependencies

Complete Software List

Configure Repository Access

Understanding Runner Settings

gitHubRunner vs. runs-on

Performance Optimization

Runner Capacity Planning

Performance Tips

Performance Metrics

Monitoring Runners

Troubleshooting

Common Issues

Security Considerations

Next Steps