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

# Testing Staging Environment

> Trigger TesterArmy test groups after each staging deployment on your own infrastructure using a saved environment and a signed group webhook.

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. Pick the group in the **Test library** rail, then open the **Webhook**
   menu in the **Run tests** row under the group name.
3. Switch the webhook **On**.
4. Copy the 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 theme={"theme":"vesper"}
- 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 theme={"theme":"vesper"}
- 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 the installation under **Integrations → GitHub**.
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.