Skip to main content

​
Overview

Connecting Spur to GitHub Actions runs your configured Test Plans when the workflow triggers and reports commit status checks. To block merging on failed tests, configure the required checks in your branch protection rules.
For @spur comment requests, generated tests, or testing instructions, see the PR Agent. It uses the Spur GitHub App and does not need the workflow files on this page.

​
What you get

Automated test execution

Test Plans run automatically on every pull request without manual intervention.

PR status checks

Pass/fail results appear directly on your pull requests.

Deployment quality gate

Tests run right before deployment, catching issues before they reach production.

Branch protection

Prevent merging pull requests with failing tests using GitHub branch protection rules.

​
Setup

1

Go to integrations

Open the Integrations page in your Spur dashboard and connect GitHub.

Open Spur Integrations

Connect Spur with GitHub to get started
2

Open GitHub settings

Once connected, find GitHub on the Integrations page and click Settings.
GitHub integration settings

Click Settings on the GitHub integration card

3

Configure your integration

If GitHub settings show tabs, select CI/CD. Review these sections before proceeding.

API key

Your unique Spur API key authenticates your GitHub repository with Spur. Copy it if you need to reference it manually.

Directory path

The path where your GitHub Actions workflow files will be stored. The default is .github/workflows. Leave this as is unless your repository uses a custom structure.

Enabled Test Plans

Select which Test Plans should run as part of your CI/CD pipeline. Click + Add Test Plan to include additional ones.

YAML files

Spur generates two workflow files for you here. You will download and add these to your repository in the next step.
Other integrations: You can also allow other integrations to be enabled for GitHub jobs.
Enable other integrations for GitHub jobs

Enable other integrations for GitHub jobs

GitHub integration configuration

The GitHub Integration Settings page

4

Add the YAML files to your repository

Download both YAML files from the settings page and add them to your repository under .github/workflows/.The Test Plan Trigger file contains your API key in its spur-github-key header. Before you commit it, store the key as a repository secret named SPUR_API_KEY and change the header to -H "spur-github-key: ${{ secrets.SPUR_API_KEY }}".
These two files are what make the integration work. Without them in your repository, Spur doesn’t trigger on pull requests and no quality gate is in place. Do not skip this step.
  • Report Generation — generates and publishes test reports after each run
  • Test Plan Trigger — tells GitHub when to trigger a Spur Test Plan run
Adding YAML files to GitHub repository

Add both YAML files to your repository's .github/workflows/ directory

5

Save changes

Click Save Changes to finalize your integration. From this point, Spur runs your selected Test Plans automatically on every pull request.

​
How the workflow files work

The two YAML files you download from the settings page serve different purposes:

​
Test Plan trigger

This workflow runs when a pull request is opened or updated. It calls the Spur webhook with your API key, the commit SHA, and the repository name, which triggers your enabled Test Plans. Each Test Plan posts an individual commit status back to the PR as tests execute. The generated file runs only on pull requests that target ext/spur/github. Change the branch under branches: to the branch your pull requests target, such as main. To run tests against a deploy preview, see Testing deploy previews. To run only some of your enabled Test Plans, see Running specific test plans.

​
Report generation

This workflow listens for status events on your repository. After each Spur Test Plan finishes and posts its commit status, the report workflow:
  1. Collects all Spur-related commit statuses for the PR
  2. Generates a markdown report table with pass, fail, pending, and error counts for each Test Plan
  3. Creates or updates a single PR comment (identified by a ## Spur CI/CD Report header) so your PR stays clean
  4. Sets a summary commit status called CICD - All tests that reflects the overall result
The summary status auto-updates as individual Test Plans complete, so you always see the latest state.

​
Using the summary status for branch protection

You can use the CICD - All tests status as a required status check in GitHub branch protection rules. This blocks merging until every Test Plan in the pipeline has passed. To set this up:
  1. Go to your repository’s Settings > Branches > Branch protection rules
  2. Enable Require status checks to pass before merging
  3. Search for and select CICD - All tests

​
Testing deploy previews

Need to test against a Vercel preview deploy or feature branch URL? Use Override URLs to redirect tests at runtime without changing your environment settings.