About -hosted runners

Overview of -hosted runners

Runners are the machines that execute jobs in a Actions workflow. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code.

provides runners that you can use to run your jobs, or you can host your own runners. Each -hosted runner is a new virtual machine (VM) hosted by with the runner application and other tools preinstalled, and is available with Ubuntu Linux, Windows, or macOS operating systems. When you use a -hosted runner, machine maintenance and upgrades are taken care of for you.

You can choose one of the standard -hosted runner options or, if you are on the Team or Enterprise Cloud plan, you can provision a runner with more cores, or a runner that's powered by a GPU processor. These machines are referred to as "larger runner." For more information, see About larger runners.

Using -hosted runners requires network access with at least 70 kilobits per second upload and download speeds.

Using a -hosted runner

To use a -hosted runner, create a job and use runs-on to specify the type of runner that will process the job, such as ubuntu-latest, windows-latest, or macos-latest. For the full list of runner types, see About -hosted runners. If you have repo: 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, 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 -hosted runners.

The following example workflow has two jobs, named Run-npm-on-Ubuntu and Run-PSScriptAnalyzer-on-Windows. When this workflow is triggered, provisions a new virtual machine for each job.

• The job named Run-npm-on-Ubuntu is executed on a Linux VM, because the job's runs-on: specifies ubuntu-latest.
• The job named Run-PSScriptAnalyzer-on-Windows is executed on a Windows VM, because the job's runs-on: specifies windows-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: 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

While the job runs, the logs and output can be viewed in the UI:

The Actions runner application is open source. You can contribute and file issues in the runner repository.

Viewing available runners for a repository

If you have repo: write access to a repository, you can view a list of the runners available to the repository.

1. On , navigate to the main page of the repository.

2. Under your repository name, click Actions.

   

3. In the left sidebar, under the "Management" section, click Runners.

4. Review the list of available -hosted runners for the repository.

5. Optionally, to copy a runner's label to use it in a workflow, click to the right of the runner, then click Copy label.

Supported runners and hardware resources

Ranges of -hosted runners are available for use in public and private repositories.

For lists of available runners, see:

• Standard runners for public repositories
• Standard runners for private repositories

-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, see Configure hardware acceleration for the Android Emulator in the Android Developers documentation.

Standard -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.

Standard -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 account's allotment of free minutes, and are then charged at the per minute rates. For more information, see About billing for Actions.

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 are compatible with arm64 -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 a development 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 Team and Enterprise Cloud plans can choose from a range of managed virtual machines that have more resources than the standard -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 runners

These larger runners are hosted by and have the runner application and other tools preinstalled.

For more information, see Using larger runners.

Runner Images

maintains our own set of VM images for our standard hosted runners. This includes the images for macOS, x64 linux and Windows images. The list of images and their included tools are managed in the actions/runner-images repository. Our arm64 images are partner images, and those are managed in the actions/partner-runner-images repository.

Preinstalled software for -owned images

The software tools included in our -owned images are updated weekly. The update process takes several days, and the list of preinstalled software on the main branch is updated after the whole deployment ends.

Workflow logs include a link to the preinstalled tools on the exact runner. To find this information in the workflow log, expand the Set up job section. Under that section, expand the Runner Image section. The link following Included Software will describe the preinstalled tools on the runner that ran the workflow.

For more information, see Viewing workflow run history.

-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 include grep, find, and which, 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 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 at actions/runner-images. This repository also contains announcements about all major software updates on runners.

Installing additional software

You can install additional software on -hosted runners. For more information, see Customizing -hosted runners.

Cloud hosts used by -hosted runners

hosts Linux and Windows runners on virtual machines in Microsoft Azure with the Actions runner application installed. The -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. hosts macOS runners in Azure data centers.

Workflow continuity

If 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 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 -hosted runner within 45 minutes, then the queued workflow run is discarded.

Administrative privileges

The Linux and macOS virtual machines both run using passwordless sudo. When you need to execute commands or install tools that require more privileges than the current user, you can use sudo 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 Actions uses for -hosted runners, you can use the REST API. For more information, see the actions key in the response of the GET /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 's own macOS cloud.

Since there are so many IP address ranges for -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 Actions IP addresses returned by the API is updated once a week.

Communication requirements for -hosted runners

A -hosted runner must establish connections to -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 -hosted runners between networks within your configuration, ensure that the following communications are allowed.

Needed for essential operations:

.com
api..com
*.actions.usercontent.com

.com
api..com
*.actions.usercontent.com

Needed for downloading actions:

codeload..com
pkg.actions.usercontent.com

codeload..com
pkg.actions.usercontent.com

Needed for publishing immutable actions:

ghcr.io

ghcr.io

Needed for uploading/downloading job summaries, logs, workflow artifacts, and caches:

results-receiver.actions.usercontent.com
*.blob.core.windows.net

results-receiver.actions.usercontent.com
*.blob.core.windows.net

Needed for runner version updates:

objects.usercontent.com
objects-origin.usercontent.com
-releases.usercontent.com
-registry-files.usercontent.com

objects.usercontent.com
objects-origin.usercontent.com
-releases.usercontent.com
-registry-files.usercontent.com

Needed for retrieving OIDC tokens:

*.actions.usercontent.com

*.actions.usercontent.com

Needed for downloading or publishing packages or containers to Packages:

*.pkg..com
pkg-containers.usercontent.com
ghcr.io

*.pkg..com
pkg-containers.usercontent.com
ghcr.io

Needed for Git Large File Storage

-cloud.usercontent.com
-cloud.s3.amazonaws.com

-cloud.usercontent.com
-cloud.s3.amazonaws.com

Needed for jobs for Dependabot updates

dependabot-actions.app.com

dependabot-actions.app.com

The etc/hosts file

-hosted runners are provisioned with an etc/hosts file that blocks network access to various cryptocurrency mining pools and malicious sites. Hosts such as MiningMadness.com and cpu-pool.com are rerouted to localhost so that they do not present a significant security risk.

File systems

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 provides to construct file paths for the home, workspace, and workflow directories.

For a list of the environment variables creates for each workflow, see Store information in variables.

Docker container filesystem

Actions that run in Docker containers have static directories under the / path. However, we strongly recommend using the default environment variables to construct file paths in Docker containers.

reserves the / path prefix and creates three directories for actions.

• //home
• //workspace - Note: Actions must be run by the default Docker user (root). Ensure your Dockerfile does not set the USER instruction, otherwise you will not be able to access _WORKSPACE.
• //workflow

Further reading

• Managing billing for 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.