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

# Testing Staging Environment

This guide walks through testing a staging environment deployed on your own infrastructure. You'll use a saved Staging environment and a group webhook with a `commitSha` to trigger tests after deployment and get results as GitHub commit check runs.

## Prerequisites

* [GitHub App](https://github.com/apps/testerarmy/installations/new) installed and connected to your repository.
* A project with tests organized in a group.
* A saved Staging environment. See [Environments](/guides/environments) if you need to create one.

## 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 and click **Save**.
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. This links test results to the commit on GitHub as a 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 two places:

* **GitHub** - a commit check run on the SHA, visible in the PR checks tab.
* **TesterArmy dashboard** - full run details with screenshots and logs.

## How `commitSha` works

Without `commitSha`, TesterArmy runs the tests but has no way to report back to GitHub. Passing it enables the integration:

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 `commitSha`** - the webhook still runs tests, but can't post results to GitHub without it.
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.