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

# Per-PR sandboxes

> Every PR gets a deterministic sandbox with API twins, tested automatically

On every PR, Arga deploys the services the PR touches into a fresh sandbox and wires them to the rest of your production services as-is. External integrations (Stripe, Slack, GitHub, Notion, and the rest) are swapped for [API twins](/concepts/digital-twins) so nothing touches real APIs. Tests are compiled from the diff and run against that sandbox, with results posting back as a GitHub check.

## How per-PR sandboxes work

<Steps>
  <Step title="Open or update a pull request">
    When you push to a monitored repository, Arga detects the change and starts planning a validation run. This happens automatically based on your trigger mode — either on new pull requests or on commits to a specific branch.
  </Step>

  <Step title="Arga forks only the changed services">
    Arga redeploys the services touched by the PR to its own infrastructure and wires them to the rest of your production services. Unchanged services stay on prod, so the sandbox mirrors your real stack without the cost of forking everything.
  </Step>

  <Step title="External integrations run on digital twins">
    Outbound calls from the sandbox to Stripe, Slack, GitHub, Notion, and the rest are intercepted by [digital twins](/concepts/digital-twins), stateful clones with real webhooks and edge cases. Nothing touches real APIs.
  </Step>

  <Step title="Tests generated from the diff run against the sandbox">
    Arga reads the diff and pulls context from connected [integrations](/integrations) (Jira, Linear, Sentry, PostHog, and more), then generates tests scoped to what changed and runs them against the sandbox.
  </Step>

  <Step title="Results post back to GitHub">
    Arga publishes results as the **Arga Validation** check on your pull request. You can also view the full timeline from the PR Checks UI.
  </Step>
</Steps>

## Set up per-PR sandboxes

<Note>PR Checks and Sandboxes require a Team or Paid plan. Run `arga whoami` to check your current billing plan.</Note>

<Info>
  **Before you start:** Per-PR sandboxes require the Arga team to configure how your services are forked and deployed. [Book a call](https://cal.com/akiratong/30min?overlayCalendar=true) so we can understand your stack — which services you run, how they're deployed, and how they connect to each other. Once configured, PR Checks and Sandboxes are fully automated.
</Info>

<Steps>
  <Step title="Connect GitHub">
    Go to [Integrations](/integrations) and connect your GitHub account if you have not already.
  </Step>

  <Step title="Select a repository">
    Open **PR Checks** in the **Previews** section of the web app. Choose the repository you want Arga to monitor.
  </Step>

  <Step title="Install the GitHub App">
    Install the Arga GitHub App for the selected repository. This gives Arga permission to listen for events and post check results.
  </Step>

  <Step title="Choose a trigger mode">
    Pick how Arga should trigger validation runs:

    * **Pull requests** — runs on every new or updated PR.
    * **Commits to branch** — runs on every push to a specific branch (for example, `main` or `staging`).
  </Step>

  <Step title="Configure options">
    Optionally adjust:

    * **PR comments** — Arga posts a comment summary on the pull request. This is enabled by default.
    * **Custom instructions** — provide additional context that applies to every run for this repository, such as "focus on the checkout flow" or "ignore visual regressions".
  </Step>

  <Step title="Save">
    Save the configuration. Arga starts monitoring the repository immediately.
  </Step>
</Steps>

## Disable validation for a repository

You can pause automatic validation for a repository without removing its configuration. In **Previews -> PR Checks**, toggle the repository off. Arga stops triggering runs for that repository until you re-enable it.

You can also toggle validation from the API using [`PATCH /validation/github/config`](/api-reference/patch-toggle-github-repo-validation).

## Start a PR validation from the CLI

You can also trigger a PR validation manually using the [CLI](/cli-and-mcp):

```bash theme={null}
arga previews pr-checks run --repo owner/repo --pr 42
```

To provide additional context:

```bash theme={null}
arga previews pr-checks run \
  --repo owner/repo \
  --pr 42 \
  --context-notes "focus on the checkout flow changes"
```

## View past runs

Recent validation activity appears in the relevant web app section: PR Checks for repository automation, Sandboxes for preview environments, and Runs or Tests for browser test execution. PR Check rows show the repository, PR number, branch, commit SHA, trigger type, and current status.

## Trigger modes

| Mode                  | When it runs                           | Use case                             |
| --------------------- | -------------------------------------- | ------------------------------------ |
| **Pull requests**     | On every new or updated PR             | Catch regressions before merging     |
| **Commits to branch** | On every push to the configured branch | Validate staging or main after merge |

## What Arga checks

Arga does not run a fixed test suite. Instead, it generates E2E tests based on what changed in the PR and what it learns from your connected tools. A typical run checks:

* Whether the changed flows still work end to end against the sandbox
* Whether integrations the PR touches behave correctly against digital twins
* Whether edge cases, failures, and error states are handled

Results include a step-by-step timeline with action descriptions and pass/fail status for each story.

## Preview environment variables

When Arga builds a PR preview, it injects a set of well-known `ARGA_PREVIEW_*` variables that describe the preview's URLs and metadata. You can reference these tokens in your own environment variables (for example, in `PRPreviewConfig` env vars) and Arga resolves them at build time. This lets you set a single value like `NEXT_PUBLIC_API_URL=${ARGA_PREVIEW_URL_BACKEND}` once and have it expand to the correct preview URL for every PR.

Supported syntax is `${ARGA_PREVIEW_*}` or `$ARGA_PREVIEW_*`. Only tokens with the `ARGA_PREVIEW_` prefix are substituted, so other `$` characters in your values (such as passwords or shell snippets) are left untouched. Unknown `ARGA_PREVIEW_*` references are left as-is.

| Variable                                         | Description                                                                                                                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ARGA_PREVIEW_PR_NUMBER`                         | The pull request number.                                                                                                                                                                    |
| `ARGA_PREVIEW_REPO`                              | The repository in `owner/repo` form.                                                                                                                                                        |
| `ARGA_PREVIEW_COMMIT_SHA`                        | The commit SHA being built (empty string if unknown).                                                                                                                                       |
| `ARGA_PREVIEW_ALIAS`                             | The per-PR alias label (for example, `pub-pr-42-my-repo`).                                                                                                                                  |
| `ARGA_PREVIEW_SCHEME`                            | The URL scheme (`https` or `http`).                                                                                                                                                         |
| `ARGA_PREVIEW_BASE_DOMAIN`                       | The base domain that preview hosts are served from.                                                                                                                                         |
| `ARGA_PREVIEW_HOST`                              | The primary preview host (`<alias>.<base-domain>`).                                                                                                                                         |
| `ARGA_PREVIEW_URL`                               | The primary preview URL.                                                                                                                                                                    |
| `ARGA_PREVIEW_URL_APP` / `ARGA_PREVIEW_HOST_APP` | Alias for the first public service in your compose file. Use this when you don't want to hardcode the service name.                                                                         |
| `ARGA_PREVIEW_URL_<SERVICE>`                     | The URL for a specific compose service that publishes ports. `<SERVICE>` is the uppercased, sanitized service name (for example, `ARGA_PREVIEW_URL_BACKEND` for a service named `backend`). |
| `ARGA_PREVIEW_HOST_<SERVICE>`                    | The host portion of the per-service URL.                                                                                                                                                    |

`ARGA_PREVIEW_*` values take precedence over any user-provided env var with the same name, so a stale entry cannot override the tokens computed for the current PR.

## Rebuild a PR preview

Each PR preview posts an **Arga Preview** check on the pull request. To recreate the preview environment from the PR's current head commit — for example, after fixing a flaky build or rotating a secret — open the **Arga Preview** check on GitHub and click **Rebuild preview**. The PR sticky comment also links to this action once the preview is ready.

Re-requesting the **Arga Preview** check from GitHub's checks UI has the same effect. Both actions queue a fresh build against the latest commit on the PR branch; rebuilds are skipped if the pull request is closed or in draft.

## PR Checks vs Sandboxes

Arga offers two ways to validate pull requests:

* **PR Checks** run automatically on every PR or branch push. Set them up once and let GitHub surface the result. See [Validate modes — PR Checks](/features/validate-modes#pr-run).
* **Sandboxes** create an isolated preview environment for a branch with service twins. Use this when you want a preview URL for manual inspection, saved tests, or deeper exploration. See [Validate modes — Sandboxes](/features/validate-modes#sandbox-run).