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

# GitHub

> Run Spur test plans automatically on every GitHub pull request and block deployments when tests fail.

## Overview

Connecting Spur to GitHub Actions adds an automated quality gate to your pull request workflow. When a PR is opened or code is pushed, Spur triggers your test plans and reports pass/fail results directly on the pull request. Failing tests block a merge before anything reaches production.

## What you get

<Columns cols={2}>
  <Card icon="play" title="Automated test execution">
    Test plans run automatically on every pull request without manual intervention.
  </Card>

  <Card icon="circle-check" title="PR status checks">
    Pass/fail results appear directly on your pull requests.
  </Card>

  <Card icon="shield-check" title="Deployment quality gate">
    Tests run right before deployment, catching issues before they reach production.
  </Card>

  <Card icon="lock" title="Branch protection">
    Prevent merging pull requests with failing tests using GitHub branch protection rules.
  </Card>
</Columns>

## Setup

<Steps>
  <Step title="Go to Integrations">
    Open the Integrations page in your Spur dashboard and connect GitHub.

    <Card icon="github" horizontal href="https://app.spurtest.com/integrations" title="Open Spur Integrations">
      Connect Spur with GitHub to get started
    </Card>
  </Step>

  <Step title="Open GitHub settings">
    Once connected, find GitHub on the integrations page and click **Settings**.

    <Frame caption="Click Settings on the GitHub integration card">
      <img src="https://mintcdn.com/spur/-kGswOS1KFY-omef/images/Screenshot2026-02-10at4.28.38PM.png?fit=max&auto=format&n=-kGswOS1KFY-omef&q=85&s=34c58187fa9ee82345a2ca84ede100cb" alt="GitHub integration settings" width="1070" height="150" data-path="images/Screenshot2026-02-10at4.28.38PM.png" />
    </Frame>
  </Step>

  <Step title="Configure your integration">
    The GitHub Integration Settings page has four sections. Review each one before proceeding.

    <Columns cols={2}>
      <Card icon="key" title="API key">
        Your unique Spur API key is displayed here. This is what authenticates your GitHub repository with Spur. Copy it if you need to reference it manually.
      </Card>

      <Card icon="folder" title="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.
      </Card>

      <Card icon="list-check" title="Enabled test plans">
        Select which test plans should run as part of your CI/CD pipeline. Click **+ Add Test Plan** to include additional ones.
      </Card>

      <Card icon="file-code" title="YAML files">
        Two workflow files are generated for you here. You will download and add these to your repository in the next step.
      </Card>
    </Columns>

    <Note>
      **Other integrations:** You can also allow other integrations to be enabled for GitHub jobs.

      <Frame caption="Enable other integrations for GitHub jobs">
        <img src="https://mintcdn.com/spur/fjkw8PRkACv6uVO8/images/Screenshot2026-02-18at4.07.55PM.png?fit=max&auto=format&n=fjkw8PRkACv6uVO8&q=85&s=6678c75aef85c257ae453ff5cb5b7471" alt="Enable other integrations for GitHub jobs" width="1164" height="178" data-path="images/Screenshot2026-02-18at4.07.55PM.png" />
      </Frame>
    </Note>

    <Frame caption="The GitHub Integration Settings page">
      <img src="https://mintcdn.com/spur/-kGswOS1KFY-omef/images/Screenshot2026-02-10at4.31.49PM.png?fit=max&auto=format&n=-kGswOS1KFY-omef&q=85&s=e0bb876d95e6dcfd310422437a3c0a4e" alt="GitHub integration configuration" width="1102" height="1100" data-path="images/Screenshot2026-02-10at4.31.49PM.png" />
    </Frame>
  </Step>

  <Step title="Add the YAML files to your repository">
    Download both YAML files from the settings page and add them to your repository under `.github/workflows/`.

    <Warning>
      These two files are what make the integration work. Without them in your repository, Spur will not trigger on pull requests and no quality gate will be 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
    </Warning>

    <Frame caption="Add both YAML files to your repository's .github/workflows/ directory">
      <img src="https://mintcdn.com/spur/-kGswOS1KFY-omef/images/Screenshot2026-02-10at4.33.04PM.png?fit=max&auto=format&n=-kGswOS1KFY-omef&q=85&s=b63ab331a3d8eb5417e2a0b74fa4e99b" alt="Adding YAML files to GitHub repository" width="1016" height="234" data-path="images/Screenshot2026-02-10at4.33.04PM.png" />
    </Frame>
  </Step>

  <Step title="Save changes">
    Click **Save Changes** to finalize your integration. From this point, Spur will run your selected test plans automatically on every pull request.
  </Step>
</Steps>

## Testing deploy previews

Need to test against a Vercel preview deploy or feature branch URL? Use [Override URLs](/running-tests/cicd/override-urls) to redirect tests at runtime without changing your environment settings.

```yaml theme={null}
- name: Run Spur Tests
  run: |
    curl -X POST \
      -H "Content-Type: application/json" \
      -H "SPUR_GITHUB_KEY: ${{ secrets.SPUR_API_KEY }}" \
      -d "{\"override_urls\": {\"default\": \"${{ steps.deploy.outputs.preview_url }}\"}}" \
      "https://app.spurtest.com/api/webhook"
```