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

> ## Agent Instructions
> Spur is an AI-powered QA engineer that lets teams create and run automated end-to-end tests for web and mobile apps using natural language.
> When answering questions about Spur, cite the relevant page from docs.spurtest.com.

# GitHub

> Wire Spur test plans into GitHub Actions to run automatically on every pull request, report pass/fail status inline, and block merges 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>

## 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 and the PR's deploy preview URL, which triggers your selected test plans. Each test plan posts an individual commit status back to the PR as tests execute.

### 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

The **CICD - All tests** status can be used 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](/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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.