Skip to main content

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.

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

1

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

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

External integrations run on digital twins

Outbound calls from the sandbox to Stripe, Slack, GitHub, Notion, and the rest are intercepted by digital twins, stateful clones with real webhooks and edge cases. Nothing touches real APIs.
4

Tests generated from the diff run against the sandbox

Arga reads the diff and pulls context from connected integrations (Jira, Linear, Sentry, PostHog, and more), then generates tests scoped to what changed and runs them against the sandbox.
5

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.

​
Set up per-PR sandboxes

PR Checks and Sandboxes require a Team or Paid plan. Run arga whoami to check your current billing plan.
Before you start: Per-PR sandboxes require the Arga team to configure how your services are forked and deployed. Book a call 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.
1

Connect GitHub

Go to Integrations and connect your GitHub account if you have not already.
2

Select a repository

Open PR Checks in the Previews section of the web app. Choose the repository you want Arga to monitor.
3

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

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).
5

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”.
6

Save

Save the configuration. Arga starts monitoring the repository immediately.

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

​
Start a PR validation from the CLI

You can also trigger a PR validation manually using the CLI: 
arga previews pr-checks run --repo owner/repo --pr 42
To provide additional context: 
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

ModeWhen it runsUse case
Pull requestsOn every new or updated PRCatch regressions before merging
Commits to branchOn every push to the configured branchValidate 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.
VariableDescription
ARGA_PREVIEW_PR_NUMBERThe pull request number.
ARGA_PREVIEW_REPOThe repository in owner/repo form.
ARGA_PREVIEW_COMMIT_SHAThe commit SHA being built (empty string if unknown).
ARGA_PREVIEW_ALIASThe per-PR alias label (for example, pub-pr-42-my-repo).
ARGA_PREVIEW_SCHEMEThe URL scheme (https or http).
ARGA_PREVIEW_BASE_DOMAINThe base domain that preview hosts are served from.
ARGA_PREVIEW_HOSTThe primary preview host (<alias>.<base-domain>).
ARGA_PREVIEW_URLThe primary preview URL.
ARGA_PREVIEW_URL_APP / ARGA_PREVIEW_HOST_APPAlias 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.
  • 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.