CodSpeed Macro Runners are dedicated bare-metal machines managed by CodSpeed that provide a stable, isolated environment for running your benchmarks. Unlike traditional CI runners, macro runners eliminate noise from virtualization and shared resources, enabling precise walltime measurements with low variance.
Read our detailed post on the consistency of CodSpeed Macro runners compared to traditional CI runners.

​
What are Macro Runners?

Macro runners are 16-core ARM64 bare-metal machines with 32 GB RAM, specifically optimized for consistency in performance measurements. They complement CodSpeed’s CPU instrumentation by providing an environment where walltime measurements are reliable and reproducible.

​
When to Use Macro Runners

Macro runners are ideal when you need to measure:
  • System calls and I/O operations that are excluded from CPU instrumentation
  • End-to-end performance including network, disk, and system interactions
  • Walltime benchmarks where actual execution time matters
  • Integration tests that require a complete system environment
CPU Instrumentation vs Macro RunnersUse CPU instrumentation for pure algorithmic performance and macro runners for system-level performance that includes I/O operations.

​
Pricing and Usage

​
Free Tier

  • 600 minutes per month included with all plans
  • Available for both Free and Pro plans
  • Perfect for getting started with walltime measurements

​
Additional Usage

  • $0.032 per minute after the free 600 minutes
  • Volume discounts available for Enterprise plans
  • Transparent, pay-as-you-use pricing
Open Source ProjectsWe’re happy to support open source projects with additional free minutes beyond the standard 600 minutes/month limit. Contact us with details about your project.

​
Setup with GitHub Actions

1

Prerequisites

Ensure you have:
  • CodSpeedHQ/action >= 3.1.0
  • A GitHub organization (macro runners don’t work with personal accounts)
  • CodSpeed enabled for your repository
Organization Required: Macro runners are only available for GitHub organizations, not personal accounts. This is due to GitHub’s permission requirements for self-hosted runners.
2

Update your workflow

Replace runs-on: ubuntu-latest with runs-on: codspeed-macro in your GitHub Actions workflow:
jobs:
  benchmarks:
    name: Run benchmarks
    runs-on: codspeed-macro
    steps:
      - uses: actions/checkout@v4
      # ...
      # 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@v4
        with:
          mode: walltime
          run: <Insert your benchmark command here>
          token: ${{ secrets.CODSPEED_TOKEN }} # optional for public repos
The workflow setup is identical to regular CodSpeed integration, just with a different runner.
3

Optimize caching (optional)

If you use caching, include ${{ runner.arch }} in your cache keys to avoid cache misses:
- uses: actions/cache@v4
  with:
    path: # insert your cache path here
    key: pip-${{ hashFiles('pyproject.toml') }}
    key: pip-${{ runner.arch }}-${{ hashFiles('pyproject.toml') }}

​
Repository Access Configuration

​
Private Repositories

Macro runners work automatically with private repositories in your organization.

​
Public Repositories

For public repositories, you need to explicitly enable macro runner access:
1

Navigate to organization settings

Go to your GitHub organization settings: Organization Settings → Actions → Runner groups → Default
2

Enable public repository access

Allow the runner group to be used by public repositories:
Enabling macro runners for public repositories

​
Next Steps

Walltime Instrument

Learn how to use the walltime instrument with macro runners

Understanding Metrics

Interpret your walltime benchmark results

Performance Checks

Set up automated performance regression detection

Pricing Details

View detailed pricing and plan options