GitHub Actions

​

Setup

​

1. Allow the Action to upload on CodSpeed

First, you need to get your CodSpeed Token. There are multiple ways to retrieve it:

• Once you enable a repository on CodSpeed, you’ll be prompted to copy the token
• You can also find it on the repository settings page

Then, create a new encrypted secret in your repository with the name CODSPEED_TOKEN and the value of your token.

​

2. Create the benchmarks workflow

The next step is to 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:

name: CodSpeed

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

jobs:
  benchmarks:
    name: Run benchmarks
    runs-on: ubuntu-latest
    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 benchmarks
        uses: CodSpeedHQ/action@v3
        with:
          token: ${{ secrets.CODSPEED_TOKEN }}
          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.

​

Sample configurations

• Python (with pytest-codspeed)
• Rust (with cargo-codspeed)
• Node.js (with codspeed-node and TypeScript)

​

3. Check the results

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

​

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

​

Advanced

​

Defining environment variables

You can define environment variables for your benchmarks by using the env key in the section of the action:

- name: Run benchmarks
  uses: CodSpeedHQ/action@v3
  env:
    MY_ENV_VAR: "my-value"
  with:
    token: ${{ secrets.CODSPEED_TOKEN }}

​

Running benchmarks in parallel CI jobs

With Github Actions, you can leverage matrix jobs to improve the performance of your benchmarks.

For example, using pytest:

jobs:
  benchmarks:
    strategy:
      matrix:
        shard: [1, 2, 3, 4]

    name: "Run benchmarks (Shard #${{ matrix.shard }})"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install required-version defined in uv.toml
        uses: astral-sh/setup-uv@v5
      - uses: actions/setup-python@v2
        with:
          python-version: 3.12.8
      - name: Run benchmarks
        uses: CodSpeedHQ/action@v3
        with:
          run:
            uv run pytest tests/benchmarks/ --codspeed --test-group=${{ matrix.shard }} --test-group-count=4
          token: ${{ secrets.CODSPEED_TOKEN }}

Learn more about benchmark sharding and how to integrate with your CI provider.