> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://tester.army/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://tester.army/_mcp/server.

# Testing Staging Environment

This guide walks through testing a staging environment deployed on your own infrastructure. You will use a saved Staging environment and a signed group webhook to trigger tests after deployment. Results always appear in TesterArmy and can also appear as a GitHub Check Run when GitHub is connected.

## Prerequisites

* A project with tests organized in a [group](/run/groups).
* A saved Staging environment. See [Environments](/guides/environments) if you need to create one, or create it from the CLI with `ta projects environments-create <projectId> --name Staging --url https://staging.example.com`.
* Optional: [connect GitHub](/integrations/github) when you want a commit Check Run.

## 1. Create a test group webhook

1. Open your project → **Tests** tab.
2. Expand the group you want to run against staging.
3. Click the **trigger badge** (lightning icon).
4. Toggle **Enable webhook** on.
5. Copy the webhook URL - the secret is shown once.

The URL looks like:

```
https://tester.army/api/v1/groups/webhook/{id}/{secret}
```

See [Group Webhooks](/run/group-webhooks) for more details.

## 2. Trigger after deployment

Once your staging deployment completes, call the webhook with the commit SHA. If the SHA belongs to the repository connected to this TesterArmy project, TesterArmy creates a best-effort GitHub Check Run.

### GitHub Actions

Add the saved Staging environment ID to your repository secrets as `TESTERARMY_STAGING_ENVIRONMENT_ID`, then add a step after your deployment job:

```yaml
- name: Run TesterArmy tests
  run: |
    curl -X POST "${{ secrets.TESTERARMY_WEBHOOK_URL }}" \
      -H "Content-Type: application/json" \
      -d "{\"commitSha\":\"${{ github.sha }}\",\"projectEnvironmentId\":\"${{ secrets.TESTERARMY_STAGING_ENVIRONMENT_ID }}\"}"
```

Add these to your repository secrets (**Settings -> Secrets and variables -> Actions**):

* `TESTERARMY_WEBHOOK_URL` - the full webhook URL including the secret.
* `TESTERARMY_STAGING_ENVIRONMENT_ID` - the saved Staging environment ID from **Project Settings -> Test environments**.

TesterArmy uses the saved staging URL and any staging-specific credential overrides attached to that environment.

### Without a saved environment

If you do not want to save Staging in TesterArmy, pass a one-off `targetUrl` and label the result as staging:

```yaml
- name: Run TesterArmy tests
  run: |
    curl -X POST "${{ secrets.TESTERARMY_WEBHOOK_URL }}" \
      -H "Content-Type: application/json" \
      -d "{\"commitSha\":\"${{ github.sha }}\",\"targetUrl\":\"${{ secrets.TESTERARMY_TARGET_URL }}\",\"environment\":\"staging\"}"
```

This only sets the run URL and Results label. It does not apply saved environment credential overrides.

## 3. View results

When tests finish, results appear in TesterArmy and can also appear in GitHub:

* **TesterArmy dashboard** - always contains full run details with screenshots and logs.
* **GitHub** - contains a Check Run only when the GitHub App is connected and the SHA belongs to the connected repository.

## How `commitSha` works

Without `commitSha`, TesterArmy still runs the tests but cannot attach a result to a GitHub commit. When GitHub is connected and the SHA resolves:

1. Tests are queued against `projectEnvironmentId` or `targetUrl` when provided, otherwise the project's configured URL.
2. A **pending** check run is created on the commit.
3. When tests complete, the check run updates with the batch summary.

## Troubleshooting

### No check run appears on GitHub

1. **GitHub App not connected** - verify installation in Project Settings.
2. **Missing or unrelated `commitSha`** - the webhook still runs tests, but cannot create a check unless the SHA belongs to the connected repository.
3. **Permissions** - the GitHub App needs **Checks: Read & Write**.

### Tests run against the wrong URL

Tests run against `projectEnvironmentId` or `targetUrl` if provided in the webhook body, otherwise the URL configured in your project settings. Make sure the selected saved environment or URL points to staging.