Skip to main content
Running benchmarks in CI environments presents unique challenges due to the inherent noise and variability of shared cloud infrastructure. Standard GitHub-hosted runners can exhibit significant performance variance.
Read our detailed post on how CI noise affects benchmark consistency.
CodSpeed instruments are designed to mitigate these challenges and gather accurate performance data even in noisy environments. The easiest way to get started running benchmarks in GitHub Actions is to use the CodSpeed GitHub Action.

​
1. Create the benchmarks workflow

Create a new workflow to run the benchmarks for your repository. You can do this by creating the codspeed.yml file in the .github/workflows directory with the following content:
.github/workflows/codspeed.yml
name: CodSpeed Benchmarks

on:
  push:
    branches:
      - "main" # or "master"
  pull_request:
  # `workflow_dispatch` allows CodSpeed to trigger backtest
  # performance analysis in order to generate initial data.
  workflow_dispatch:

permissions: # optional for public repositories
  contents: read # required for actions/checkout
  id-token: write # required for OIDC authentication with CodSpeed
  
jobs:
  benchmarks:
    name: Run benchmarks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # ...
      # 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: instrumentation
          run: <Insert your benchmark command here>
The most important step of this workflow is the usage of CodSpeedHQ/action. This action will configure the CodSpeed environment and upload the benchmarks results.
Make sure to include pull_request in the on section of the workflow. This is required to have reports on pull requests correctly working.Learn more about baseline report selection.
Public repositoriesCodSpeed allows tokenless uploads for public repositories, allowing runs to be triggered from public forks directly.To enable this, you can simply omit the permissions section.Learn more about authentication methods.

​
Sample configurations

​
2. Check the results

Once the workflow is created, your pull requests will receive a performance report comment and will also receive some additional checks: Pull Request Result Pull Request Result

​
3. Next Steps

Now that everything is up and running (and hopefully green 🎉), you can start enhancing your workflow to get the most out of CodSpeed.

Configure GitHub Actions for CodSpeed

Learn how to configure authentication methods and advanced options for GitHub Actions

Explore the Performance Metrics

Understand the performance metrics generated by CodSpeed

Enforce Performance Checks

Make sure you or team members never merge unexpected performance regressions

Dive in Trace Generation

Get detailed performance traces for your benchmarks

Shard the execution of your benchmarks

Run your benchmarks in parallel to speed up your CI