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

# Custom Infrastructure

If your app isn't deployed on Vercel or Coolify, you can still wire up PR testing with a group webhook. Trigger it from GitHub Actions, GitLab CI, Jenkins, a shell script, or any other system that can send an HTTP request after a deployment finishes.

## How it works

1. You create a webhook on a test group in the TesterArmy dashboard.
2. After your own CI deploys a preview, it `POST`s to the webhook URL with the commit SHA (and optionally the preview URL).
3. TesterArmy runs the tests in the group against that URL and posts a GitHub check run back on the commit.

## 1. Generate the webhook

1. Open your project → **Tests** tab.
2. Expand the test group you want to run on each deploy.
3. Click the **trigger badge** (lightning icon) and toggle **Enable webhook** on.
4. Copy the URL that's shown - the secret is only revealed once.

The URL looks like:

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

Store it as a secret in your CI system. See [Group Webhooks](/run/group-webhooks) for the full reference (rate limits, mobile overrides, response format).

## 2. Trigger it from your CI

Call the webhook after your deployment step. Pass `commitSha` so results link back to the PR on GitHub, and `targetUrl` if you need to override the URL under test. If the deployment is not a PR preview, pass `environment` so the run appears under the right Results filter.

### GitHub Actions

```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\"}"
```

### GitLab CI

```yaml
testerarmy:
  stage: test
  script:
    - |
      curl -X POST "$TESTERARMY_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -d "{\"commitSha\":\"$CI_COMMIT_SHA\",\"targetUrl\":\"$TESTERARMY_TARGET_URL\",\"environment\":\"staging\"}"
```

### Any shell

```bash
curl -X POST "$TESTERARMY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"commitSha":"'"$COMMIT_SHA"'","targetUrl":"'"$DEPLOY_URL"'","environment":"staging"}'
```

## Payload fields

| Field                  | Required             | Description                                                                                                                                                                 |
| ---------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commitSha`            | No (but recommended) | Links results to the commit on GitHub as a check run. Without it, tests still run but nothing is posted to GitHub.                                                          |
| `targetUrl`            | No                   | Overrides the URL under test for this run. If omitted, tests run against the URL configured in your project settings.                                                       |
| `environment`          | No                   | Marks the run as `production`, `staging`, or `preview` in Results. Runs with `targetUrl` default to `preview` when omitted.                                                 |
| `projectEnvironmentId` | No                   | Selects a saved project environment by ID. Static environments provide their configured URL and environment-specific credential overrides. PR Preview requires `targetUrl`. |

## Environment labels

Use `environment` to control where the run appears in the Results environment filter:

* `production` - production deployments and monitoring runs.
* `staging` - staging or pre-production deployments.
* `preview` - PR previews and one-off preview URLs.

When `targetUrl` is present and `environment` is omitted, TesterArmy marks the run as `preview`. For staging pipelines, always pass `environment: "staging"`.

For [saved environments](/guides/environments), use the `id` returned by `GET /api/v1/projects/{projectId}` or copy it from **Project Settings → Test environments**. Send that value as `projectEnvironmentId`. This preserves the stable environment identity, applies environment-specific credential overrides, and still allows PR Preview runs to use a per-deployment `targetUrl`.

Use `environment` only when you need to label/filter results. It does not select a saved environment row by name, and it does not apply credential overrides.

## Results

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

For a walkthrough focused on a staging environment, see [Testing Staging Environment](/guides/testing-staging).

## Troubleshooting

### No check run on the PR

1. **Missing `commitSha`** - the webhook runs tests, but can't post to GitHub without it.
2. **GitHub App not connected** - verify installation in Project Settings.
3. **Permissions** - the GitHub App needs **Checks: Read & Write**.

### `401 Unauthorized`

The webhook ID or secret is wrong. Regenerate the webhook on the group and update your CI secret.

### `403 Forbidden`

The webhook is disabled. Open the group's trigger panel and toggle **Enable webhook** back on.

### Tests run against the wrong URL

Tests use `targetUrl` from the payload if provided, otherwise the URL configured in your project settings. Check both.