> ## Documentation Index
> Fetch the complete documentation index at: https://codspeed.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Macro Runners on GitHub Actions

> Run the benchmark jobs of your GitHub Actions workflows on CodSpeed macro runners

[Macro runners](https://codspeed.io/docs/features/macro-runners.md) are bare-metal machines managed by
CodSpeed, for [walltime](https://codspeed.io/docs/instruments/walltime.md) measurements with low variance.
A GitHub-hosted runner shares its host with other tenants, so the walltime of a
benchmark moves from one run to the next for reasons unrelated to your code. A
macro runner is dedicated to your job for its whole duration.

On GitHub Actions, CodSpeed registers a macro runner in your organization for
each queued benchmark job and removes it once the job is done. Your side of it
is the `runs-on` label of the benchmark job.

## Prerequisites

* `CodSpeedHQ/action >= 3.1.0`.
* A GitHub organization. Registering a self-hosted runner on a repository rather
  than on an organization needs the **Repository: Administration** permission,
  which is too broad, so macro runners are not available on personal accounts.
  Transfer the repository to an organization to use them.
* CodSpeed enabled on the repository.

## 1. Point the benchmark job at a macro runner

Replace `runs-on: ubuntu-latest` with the label of the
[runner](https://codspeed.io/docs/features/macro-runners.md#runners) you want, and set the `mode` of the
action to `walltime`:

> [tab] AMD Ryzen 9950X
>
> ```yaml highlight={4,16} theme={null}
> jobs:
>   benchmarks:
>     name: Run benchmarks
>     runs-on: codspeed-macro-x64-ryzen-9950x-ubuntu-24-04
>     steps:
>       - uses: actions/checkout@v7
>       # ...
>       # Setup your environment here:
>       #  - Configure your Python/Rust/Node version
>       #  - Install your dependencies
>       #  - Build your benchmarks (if using a compiled language)
>       # ...
>       - name: Run the benchmarks
>         uses: CodSpeedHQ/action@v5
>         with:
>           mode: walltime
>           run: <Insert your benchmark command here>
> ```

> [tab] AWS Graviton
>
> ```yaml highlight={4,16} theme={null}
> jobs:
>   benchmarks:
>     name: Run benchmarks
>     runs-on: codspeed-macro-arm64-graviton-ubuntu-22-04
>     steps:
>       - uses: actions/checkout@v7
>       # ...
>       # Setup your environment here:
>       #  - Configure your Python/Rust/Node version
>       #  - Install your dependencies
>       #  - Build your benchmarks (if using a compiled language)
>       # ...
>       - name: Run the benchmarks
>         uses: CodSpeedHQ/action@v5
>         with:
>           mode: walltime
>           run: <Insert your benchmark command here>
> ```

Everything else about the workflow is unchanged, see
[the GitHub Actions guide](https://codspeed.io/docs/integrations/ci/github-actions.md#1-create-the-benchmarks-workflow).

> [!TIP]
>
> **Caching**
>
> A macro runner may not share the architecture of the GitHub-hosted runners your
> other jobs use, so include `${{ runner.arch }}` in cache keys, or a job restores
> artifacts built for another architecture:
>
> ```yaml {4} theme={null}
> - uses: actions/cache@v4
>   with:
>     path: # insert your cache path here
>     key: pip-${{ hashFiles('pyproject.toml') }} # [!code --]
>     key: pip-${{ runner.arch }}-${{ hashFiles('pyproject.toml') }} # [!code ++]
> ```

## 2. Open a pull request

Open a pull request from the branch carrying the change: the benchmark job runs
on a macro runner and the pull request receives its performance report.

The walltime measurements of a run are comparable to the baseline recorded on
your default branch only if both ran on macro runners, so merge the change to
record a first baseline on a macro runner.

## Repository access

### Private repositories

Macro runners work with the private repositories of your organization without
further setup.

### Public repositories

GitHub keeps self-hosted runners away from public repositories by default, since
a pull request from a fork could run code on them. To use macro runners on a
public repository, go to **Organization Settings** → **Actions** → **Runner
groups** → **Default** in GitHub and allow public repositories:

![Enabling macro runners for public repositories](https://mintcdn.com/codspeed/_9gjNuBHMdsdxHot/instruments/walltime/assets/github-public-repo-access.png?fit=max\&auto=format\&n=_9gjNuBHMdsdxHot\&q=85\&s=fd62b02d6c9d620f4fa8723334d568c3)

> [!NOTE]
>
> A former label keeps working and lands on the same runner as the current one:
>
> * `codspeed-macro-x86-ryzen-9950x-ubuntu-24-04` for
>   `codspeed-macro-x64-ryzen-9950x-ubuntu-24-04`.
> * `codspeed-macro` for `codspeed-macro-arm64-graviton-ubuntu-22-04`, the label
>   the Graviton runner had before the machines were named individually.

## Next Steps

> [card] [Macro Runners](https://codspeed.io/docs/features/macro-runners.md)
>
> The runners, and what they are for

> [card] [Walltime Instrument](https://codspeed.io/docs/instruments/walltime.md)
>
> Measure and interpret walltime benchmarks

> [card] [Configure GitHub Actions](https://codspeed.io/docs/integrations/ci/github-actions/configuration.md)
>
> Authentication, parallel jobs and advanced options

> [card] [Performance Checks](https://codspeed.io/docs/features/performance-checks.md)
>
> Catch regressions on every pull request


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.