Skip to main content
Set up the PR Agent once for each Application. After that, Spur uses your saved deployment, environment, and instructions every time it tests a PR. Testing can start automatically or from a bare @spur comment.

Before you start

The PR Agent is in private beta. Contact Spur if it is not enabled for your Application. Prepare these items:
  • A GitHub repository and permission to install or approve the Spur GitHub App.
  • A deployed web app Spur can reach: a preview for each PR or a shared QA site.
  • A web environment with the site URL and any test accounts, variables, or data your app needs.
  • A PR with a change you can check in the browser.
The GitHub App reads code and metadata and has write access to issues, pull requests, and commit statuses. It cannot push code or merge your PR. Anyone who requests tests needs write, maintain, or admin access to the repository.

Connect repositories

1

Open GitHub settings

Select your Application, open GitHub settings, and select PR Agent. If needed, connect GitHub from Integrations first.
2

Open guided setup

Click Set up PR Agent, or Guided setup for an existing configuration. The sections are Overview, Repositories, Deployment, Run policy, Instructions, and Review.
3

Connect and enable repositories

Click Connect GitHub and finish the installation in GitHub for the repositories you want to test. If an organization owner must approve the App, connect the repositories again from Spur after they approve it.If the App is already installed, link that installation when Spur offers it. Then enable the repositories in Spur. To change which repositories the App can access, click Manage GitHub access, then click Refresh.
4

Review and save

Set the deployment, run policy, and instructions as described below. On Review, click Save setup. Saving does not start any tests.

Choose the environment and deployment

Spur preselects the Spur environment when your Application has only one web environment or one default. Keep it if it has the test accounts and data you want. If the field is empty, select a web environment. After you save, you do not need to name an environment in each comment. The two settings do different jobs:
Spur environment and deployment target controls in PR Agent settings

Keep the default test configuration, or change it when a repository needs different accounts or data.

Preview for each PR

For Vercel, click Connect Vercel, authorize access, and select the project that deploys your app. With PR preview · Latest commit, Spur tests the build of the PR’s latest commit. Spur checks whether it can open protected previews. If Spur asks, create a Protection Bypass for Automation secret in Vercel, enter it under Bypass secret, and click Verify. If no preview exists yet, deploy one and click Check again. Without a Vercel connection, select PR preview · From GitHub. Spur then uses supported preview links on the PR, including Shopify theme previews. If a PR has several storefronts, name the default one in Testing instructions. You can also describe your per-PR URL pattern there.

Shared QA or staging site

Wait for the change to deploy, then include the site URL in your request:
A QA URL in your saved instructions does not select the site. Name the URL in the request, and confirm that the shared site has the change you want to test. If a connected Vercel environment deploys one branch, Spur can test its latest ready deployment. The report notes when that build may not include the PR. Pick test flows and accounts that are safe for the target, especially on a live site.

Choose when Spur runs

This setting controls when testing starts. In both modes, Spur chooses and runs the tests. With Manual, someone comments @spur when they want the PR tested. With Automatic, Spur starts when a PR opens or gets a selected label. Set the first run and later commits separately. During setup, use Run policy. After setup, use When Spur runs. For example, you can start the first run with a comment and let later commits start new runs automatically. Automatic first runs wait until a draft PR is ready for review. For label-based testing, later automatic runs need a selected label to stay on the PR. Rerun failed tests retries the tests that did not pass in the latest completed run, including errors and unfinished tests. If every test passed, Spur skips the rerun. If no earlier run completed, Spur checks the full PR instead. Check the full PR again looks at the updated change and picks the relevant tests again. It does not run every saved test in your Application. A change scope rule, such as “Run for changes to checkout or payments. Skip documentation-only changes.”, applies only to automatic runs. You can still request tests in a comment.

Add testing instructions and a glossary

Testing instructions are optional. Spur already reads the code change, the PR description, and linked tickets. Use instructions for facts those sources leave out, such as your terms, test accounts, or required data. Your team then does not have to repeat them on every PR.
1

Select the settings scope

Under Run settings, use Settings for to select Shared defaults or a repository. Click Customize for this repository if it needs its own configuration.
2

Describe your app and test setup

Click Edit beside Testing instructions. Include your glossary, roles, important flows, test-data requirements, and the default preview or market if needed.
Testing instructions editor with example terminology, account guidance, and test-data requirements

Use shared instructions for the terminology and setup your team would otherwise repeat.

3

Insert credentials securely

Click Insert variable to add an encrypted variable from the selected environment. To make a new one, click Create encrypted variable in the picker. Keep passwords and tokens out of plain-text instructions and GitHub comments.
4

Save changes

Click Save changes. Done closes the editor but does not save the settings.
For example, a storefront team might save:
Replace these lines with facts about your app, and insert the credential variables it needs. Update the instructions when your app changes. A PR comment can override them for one request without changing what you saved.

Include linked tickets

Link requirements in the PR description or in your request. Spur reads GitHub issues from the same repository. It also reads tickets from the Linear, Jira, Azure DevOps, and ClickUp integrations connected to your Application. To check these connections, click Manage ticket sources. If Spur cannot open a ticket, describe the expected behavior in the PR or the request.

Change repository settings

Repositories use the Shared defaults of their Application unless you customize them. Click Customize for this repository to give a repository its own settings, or Use shared defaults to undo that. Save your changes when you finish. Disabling a repository stops new requests from starting tests. Tests that are already running continue. To stop them, comment @spur stop on the PR.

Try it on a real PR

Pick a PR with a visible change and a ready deployment. Post a new comment that contains only @spur. Spur picks and runs the checks with your saved setup. In the report, check the commit, the deployment, and the Spur environment. Then open a result to see the evidence. When this works, you can turn on automatic testing for later PRs. Extra guidance is optional. Start with a small PR, and review the first results with the engineer who made the change. When you add guidance, describe the result you want and any context the PR lacks. Spur writes the browser steps. To edit saved steps yourself, see the Web Prompting Guide.

Troubleshoot setup