Overview of GitHub-hosted runners
Runners are the machines that execute jobs in a GitHub Actions workflow. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code.
GitHub provides runners that you can use to run your jobs, or you canhost your own runners.Each GitHub-hosted runner is a new virtual machine (VM) hosted by GitHub with the runner application and other tools preinstalled, and is available with Ubuntu Linux, Windows, or macOS operating systems. When you use a GitHub-hosted runner, machine maintenance and upgrades are taken care of for you.
You can choose one of the standard GitHub-hosted runner options or, if you are on the GitHub Team or GitHub Enterprise Cloud plan, you can provision a runner with more cores, or a runner that's powered by a GPU or ARM processor. These machines are referred to as "larger runner." For more information, see "About larger runners."
Using GitHub-hosted runners requires network access with at least 70 kilobits per second upload and download speeds.
Using a GitHub-hosted runner
To use a GitHub-hosted runner, create a job and useruns-on
to specify the type of runner that will process the job, such asubuntu-latest
,windows-latest
,ormacos-latest
.For the full list of runner types, see "About GitHub-hosted runners."If you haverepo: write
access to a repository, you can view a list of the runners available to use in workflows in the repository. For more information, see "Viewing available runners for a repository."
When the job begins, GitHub automatically provisions a new VM for that job. All steps in the job execute on the VM, allowing the steps in that job to share information using the runner's filesystem. You can run workflows directly on the VM or in a Docker container. When the job has finished, the VM is automatically decommissioned.
The following diagram demonstrates how two jobs in a workflow are executed on two different GitHub-hosted runners.
The following example workflow has two jobs, namedRun-npm-on-Ubuntu
andRun-PSScriptAnalyzer-on-Windows
.When this workflow is triggered, GitHub provisions a new virtual machine for each job.
- The job named
Run-npm-on-Ubuntu
is executed on a Linux VM, because the job'sruns-on:
specifiesubuntu-latest
. - The job named
Run-PSScriptAnalyzer-on-Windows
is executed on a Windows VM, because the job'sruns-on:
specifieswindows-latest
.
name: Run commands on different operating systems on: push: branches: [ main ] pull_request: branches: [ main ] jobs: Run-npm-on-Ubuntu: name: Run npm on Ubuntu runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '14' - run: npm help Run-PSScriptAnalyzer-on-Windows: name: Run PSScriptAnalyzer on Windows runs-on: windows-latest steps: - uses: actions/checkout@v4 - name: Install PSScriptAnalyzer module shell: pwsh run: | Set-PSRepository PSGallery -InstallationPolicy Trusted Install-Module PSScriptAnalyzer -ErrorAction Stop - name: Get list of rules shell: pwsh run: | Get-ScriptAnalyzerRule
name:Runcommandsondifferentoperatingsystems
on:
push:
branches:[main]
pull_request:
branches:[main]
jobs:
Run-npm-on-Ubuntu:
name:RunnpmonUbuntu
runs-on:ubuntu-latest
steps:
-uses:actions/checkout@v4
-uses:actions/setup-node@v4
with:
node-version:'14'
-run:npmhelp
Run-PSScriptAnalyzer-on-Windows:
name:RunPSScriptAnalyzeronWindows
runs-on:windows-latest
steps:
-uses:actions/checkout@v4
-name:InstallPSScriptAnalyzermodule
shell:pwsh
run:|
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module PSScriptAnalyzer -ErrorAction Stop
-name:Getlistofrules
shell:pwsh
run:|
Get-ScriptAnalyzerRule
While the job runs, the logs and output can be viewed in the GitHub UI:
The GitHub Actions runner application is open source. You can contribute and file issues in therunnerrepository.
Viewing available runners for a repository
If you haverepo: write
access to a repository, you can view a list of the runners available to the repository.
-
On GitHub, navigate to the main page of the repository.
-
Under your repository name, clickActions.
-
In the left sidebar, under the "Management" section, clickRunners.
-
Review the list of available GitHub-hosted runners for the repository.
-
Optionally, to copy a runner's label to use it in a workflow, clickto the right of the runner, then clickCopy label.
Note:Enterprise and organization owners can create runners from this page. To create a new runner, clickNew runnerat the top right of the list of runners to add runners to the repository.
For more information, see "Managing larger runners"and"Adding self-hosted runners."
Supported runners and hardware resources
GitHub-hosted runners are available for use in both public and private repositories.
GitHub-hosted Linux runners support hardware acceleration for Android SDK tools, which makes running Android tests much faster and consumes fewer minutes. For more information on Android hardware acceleration, seeConfigure hardware acceleration for the Android Emulatorin the Android Developers documentation.
Note
The-latest
runner images are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.
Warning:Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.
Standard GitHub-hosted runners for public repositories
For public repositories, jobs using the workflow labels shown in the table below will run on virtual machines with the associated specifications. The use of these runners on public repositories is free and unlimited.
Virtual Machine | Processor (CPU) | Memory (RAM) | Storage (SSD) | Workflow label |
---|---|---|---|---|
Linux | 4 | 16 GB | 14 GB |
ubuntu-latest ,ubuntu-24.04 [Beta],ubuntu-22.04 ,ubuntu-20.04
|
Windows | 4 | 16 GB | 14 GB |
windows-latest ,windows-2022 ,windows-2019
|
macOS | 3 | 14 GB | 14 GB |
macos-12
|
macOS | 4 | 14 GB | 14 GB |
macos-13
|
macOS | 3 (M1) | 7 GB | 14 GB |
macos-latest ormacos-14
|
Standard GitHub-hosted runners for private repositories
For private repositories, jobs using the workflow labels shown in the table below will run on virtual machines with the associated specifications. These runners use your GitHub account's allotment of free minutes, and are then charged at the per minute rates. For more information, see "About billing for GitHub Actions."
Virtual Machine | Processor (CPU) | Memory (RAM) | Storage (SSD) | Workflow label |
---|---|---|---|---|
Linux | 2 | 7 GB | 14 GB |
ubuntu-latest ,ubuntu-24.04 [Beta],ubuntu-22.04 ,ubuntu-20.04
|
Windows | 2 | 7 GB | 14 GB |
windows-latest ,windows-2022 ,windows-2019
|
macOS | 3 | 14 GB | 14 GB |
macos-12
|
macOS | 4 | 14 GB | 14 GB |
macos-13
|
macOS | 3 (M1) | 7 GB | 14 GB |
macos-latest ormacos-14
|
Workflow logs list the runner used to run a job. For more information, see "Viewing workflow run history."
Limitations for arm64 macOS runners
- All actions provided by GitHub are compatible with arm64 GitHub-hosted runners. However, community actions may not be compatible with arm64 and need to be manually installed at runtime.
- Nested-virtualization and Metal Performance Shaders (MPS) are not supported due to the limitation of Apple's Virtualization Framework.
- Networking capabilities such as Azure private networking and assigning static IPs are not currently available for macOS larger runners.
- The arm64 macOS runners do not have a static UUID/UDID assigned to them because Apple does not support this feature. However, Intel MacOS runners are assigned a static UDID, specifically
4203018E-580F-C1B5-9525-B745CECA79EB
.If you are building and signing on the same host you plan to test the build on, you can sign with adevelopment provisioning profile.If you do require a static UDID, you can use Intel runners and add their UDID to your Apple Developer account.
Larger runners
Customers on GitHub Team and GitHub Enterprise Cloud plans can choose from a range of managed virtual machines that have more resources than thestandard GitHub-hosted runners.These machines are referred to as "larger runner." They offer the following advanced features:
- More RAM, CPU, and disk space
- Static IP addresses
- Azure private networking
- The ability to group runners
- Autoscaling to support concurrent workflows
- GPU-powered and ARM-powered runners
These larger runners are hosted by GitHub and have the runner application and other tools preinstalled.
For more information, see "Using larger runners."
Supported software
The software tools included in GitHub-hosted runners are updated weekly. The update process takes several days, and the list of preinstalled software on themain
branch is updated after the whole deployment ends.
Preinstalled software
Workflow logs include a link to the preinstalled tools on the exact runner. To find this information in the workflow log, expand theSet up job
section. Under that section, expand theRunner Image
section. The link followingIncluded Software
will describe the preinstalled tools on the runner that ran the workflow.
For more information, see "Viewing workflow run history."For the overall list of included tools for each runner operating system, see theAvailable Imagesdocumentation the runner images repository.
GitHub-hosted runners include the operating system's default built-in tools, in addition to the packages listed in the above references. For example, Ubuntu and macOS runners includegrep
,find
,andwhich
,among other default tools.
You can also view a software bill of materials (SBOM) for each build of the Windows and Ubuntu runner images. For more information, see "Security hardening for GitHub Actions."
Using preinstalled software
We recommend using actions to interact with the software installed on runners. This approach has several benefits:
- Usually, actions provide more flexible functionality like version selection, ability to pass arguments, and parameters
- It ensures the tool versions used in your workflow will remain the same regardless of software updates
If there is a tool that you'd like to request, please open an issue atactions/runner-images.This repository also contains announcements about all major software updates on runners.
Installing additional software
You can install additional software on GitHub-hosted runners. For more information, see "Customizing GitHub-hosted runners".
Cloud hosts used by GitHub-hosted runners
GitHub hosts Linux and Windows runners on virtual machines in Microsoft Azure with the GitHub Actions runner application installed. The GitHub-hosted runner application is a fork of the Azure Pipelines Agent. Inbound ICMP packets are blocked for all Azure virtual machines, so ping or traceroute commands might not work. GitHub hosts macOS runners in Azure data centers.
For Linux and Windows runners, GitHub usesDadsv5-series
virtual machines. For more information, seeDasv5 and Dadsv5-seriesin the Microsoft Azure documentation.
GPU runners useNCasT4_v3-series
virtual machines. For more information, seeNCasT4_v3-seriesin the Microsoft Azure documentation.
Workflow continuity
If GitHub Actions services are temporarily unavailable, then a workflow run is discarded if it has not been queued within 30 minutes of being triggered. For example, if a workflow is triggered and the GitHub Actions services are unavailable for 31 minutes or longer, then the workflow run will not be processed.
In addition, if the workflow run has been successfully queued, but has not been processed by a GitHub-hosted runner within 45 minutes, then the queued workflow run is discarded.
Administrative privileges
The Linux and macOS virtual machines both run using passwordlesssudo
.When you need to execute commands or install tools that require more privileges than the current user, you can usesudo
without needing to provide a password. For more information, see the "Sudo Manual."
Windows virtual machines are configured to run as administrators with User Account Control (UAC) disabled. For more information, see "How User Account Control works"in the Windows documentation.
IP addresses
To get a list of IP address ranges that GitHub Actions uses for GitHub-hosted runners, you can use the GitHub REST API. For more information, see theactions
key in the response of theGET /meta
endpoint. For more information, see "REST API endpoints for meta data."
Windows and Ubuntu runners are hosted in Azure and subsequently have the same IP address ranges as the Azure datacenters. macOS runners are hosted in GitHub's own macOS cloud.
Since there are so many IP address ranges for GitHub-hosted runners, we do not recommend that you use these as allowlists for your internal resources. Instead, we recommend you use larger runners with a static IP address range, or self-hosted runners. For more information, see "Using larger runners"or"About self-hosted runners."
The list of GitHub Actions IP addresses returned by the API is updated once a week.
Communication requirements for GitHub-hosted runners and GitHub
A GitHub-hosted runner must establish connections to GitHub-owned endpoints to perform essential communication operations. In addition, your runner may require access to additional networks that you specify or utilize within an action.
To ensure proper communications for GitHub-hosted runners between networks within your configuration, ensure that the following communications are allowed.
Note
Some of the domains listed are configured usingCNAME
records. Some firewalls might require you to add rules recursively for allCNAME
records. Note that theCNAME
records might change in the future, and that only the domains listed will remain constant.
Needed for essential operations:
github api.github *.actions.githubusercontent
github
api.github
*.actions.githubusercontent
Needed for downloading actions:
codeload.github ghcr.io *.actions.githubusercontent
codeload.github
ghcr.io
*.actions.githubusercontent
Needed for uploading/downloading job summaries, logs, workflow artifacts, and caches:
results-receiver.actions.githubusercontent *.blob.core.windows.net
results-receiver.actions.githubusercontent
*.blob.core.windows.net
Needed for runner version updates:
objects.githubusercontent objects-origin.githubusercontent github-releases.githubusercontent github-registry-files.githubusercontent
objects.githubusercontent
objects-origin.githubusercontent
github-releases.githubusercontent
github-registry-files.githubusercontent
Needed for retrieving OIDC tokens:
*.actions.githubusercontent
*.actions.githubusercontent
Needed for downloading or publishing packages or containers to GitHub Packages:
*.pkg.github ghcr.io
*.pkg.github
ghcr.io
Needed for Git Large File Storage
github-cloud.githubusercontent github-cloud.s3.amazonaws
github-cloud.githubusercontent
github-cloud.s3.amazonaws
Theetc/hosts
file
GitHub-hosted runners are provisioned with anetc/hosts
file that blocks network access to various cryptocurrency mining pools and malicious sites. Hosts such as MiningMadness and cpu-pool are rerouted to localhost so that they do not present a significant security risk.
File systems
GitHub executes actions and shell commands in specific directories on the virtual machine. The file paths on virtual machines are not static. Use the environment variables GitHub provides to construct file paths for thehome
,workspace
,andworkflow
directories.
Directory | Environment variable | Description |
---|---|---|
home | HOME | Contains user-related data. For example, this directory could contain credentials from a login attempt. |
workspace | GITHUB_WORKSPACE | Actions and shell commands execute in this directory. An action can modify the contents of this directory, which subsequent actions can access. |
workflow/event.json | GITHUB_EVENT_PATH | ThePOST payload of the webhook event that triggered the workflow. GitHub rewrites this each time an action executes to isolate file content between actions. |
For a list of the environment variables GitHub creates for each workflow, see "Store information in variables."
Docker container filesystem
Actions that run in Docker containers have static directories under the/github
path. However, we strongly recommend using the default environment variables to construct file paths in Docker containers.
GitHub reserves the/github
path prefix and creates three directories for actions.
/github/home
/github/workspace
-Note:GitHub Actions must be run by the default Docker user (root). Ensure your Dockerfile does not set theUSER
instruction, otherwise you will not be able to accessGITHUB_WORKSPACE
./github/workflow
Further reading
- "Managing billing for GitHub Actions"
- You can use a matrix strategy to run your jobs on multiple images. For more information, see "Running variations of jobs in a workflow."