> ## 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. # Set Up the PR Agent > Connect your repository, prepare a testable preview, and give Spur the context it needs to check your changes. 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](https://docs.spurtest.com/additional-resources/contact-us.md) if it is not enabled for your Application. Prepare these items: * A GitHub repository and permission to install or approve the [Spur GitHub App](https://github.com/apps/spurtestai). * A deployed web app Spur can reach: a preview for each PR or a shared QA site. * A web [environment](https://docs.spurtest.com/authoring-tests/environments/environments.md) 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](https://app.spurtest.com/integrations/github), 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: | Setting | Purpose | | - | - | | **Spur environment** | Supplies saved tests, variables, and test configuration. | | **Deployment target** | Selects the website where Spur checks the change. | ![Spur environment and deployment target controls in PR Agent settings](https://mintcdn.com/spur/ik0kTuD3DFwA9eQf/images/pr-agent/environment-and-deployment.png?fit=max\&auto=format\&n=ik0kTuD3DFwA9eQf\&q=85\&s=75541dc48b3bd70ab0d9aefcb97f5c94) 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: ```text theme={null} @spur check the checkout changes on https://qa.example.com. Use our usual test account and test payment details. ``` 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**. | Setting | Choices | | - | - | | First run | **Manual**, or **Automatic** for **Every new PR** or **When a label is added**. | | Later commits | **Do nothing**, **Rerun failed tests**, or **Check the full PR again**. | | Change scope | **Any change** or **Only the changes I describe**. | 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](https://mintcdn.com/spur/ik0kTuD3DFwA9eQf/images/pr-agent/testing-instructions.png?fit=max\&auto=format\&n=ik0kTuD3DFwA9eQf\&q=85\&s=bed41479387f0a24f1ad4cda8f0e7bc6) 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](https://docs.spurtest.com/authoring-tests/test-side-peek/step-types/variables/encrypted-variables.md) 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: ```text theme={null} A basket is the shopping cart. A member is a signed-in customer. Use the AU storefront preview unless the request names another market. Prioritize guest checkout, discounts, and member sign-in. Use the test account configured for this environment. Use products labeled Demo and sandbox payment details at checkout. Loyalty points are not enabled in preview builds. ``` 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](https://docs.spurtest.com/running-tests/cicd/github-agent.md#add-guidance-when-you-need-it) is optional. ## Recommended practices Start with a small PR, and review the first results with the engineer who made the change. | Recommend | Avoid | | - | - | | Start with one or two repositories and a small, visible change. Confirm the setup with one `@spur` comment before you turn on automatic testing. | Testing a large release PR first, or expecting browser tests for a change that users cannot see. | | Confirm that the preview has the change and that the test account can sign in there. Check deployment protection first. | Assuming that a production login also works on a new preview. | | Explain the intended behavior in the PR and link its requirements. Add your terminology, roles, and recurring setup to **Testing instructions**. | Relying on the diff alone to explain business rules, or repeating the same context in every comment. | | Keep reusable login steps in saved login tests, with credentials in encrypted variables. Prepare the CMS content, products, and other test data that tests need. | Plain-text passwords, long copied login procedures, or a test that depends on data that does not exist. | | Name the default storefront or market when a repository has several previews. | Leaving Spur to guess between similar previews. | | Review the evidence and save useful tests. Turn on automatic testing after the first PRs give you useful results. | Treating a pass as proof that Spur checked every possible regression, or saving every test without review. | 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](https://docs.spurtest.com/getting-started/web-prompting.md). ## Troubleshoot setup | What you see | What to check | | - | - | | No response | Post a new PR conversation comment with `@spur` outside quotes and code. Confirm that the Spur GitHub App can access the repository. Editing an old comment does not request new tests. | | Setup or access message | Select the correct Application, confirm beta access, enable the repository, and save a web environment in PR Agent settings. | | Missing or failed preview | Check the build, the connected project, or the preview link. For a shared QA site, put its URL in the request. | | Login or preview protection failure | Test the login on that preview, and check its encrypted variables and Vercel access. | | Wrong target | Name the preview and Spur environment you want in a new comment. Then correct the shared defaults if needed. | | Unclear request | Add the missing behavior, target, or other detail in a new `@spur` comment. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.