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

# Deployment audits

> Audit each SHA that reaches an environment, and tell Struct about deploys via GitHub Deployments or a webhook

A **deployment audit** checks a SHA that reached an environment against your production telemetry, recent pull requests, and code. Struct posts the result in Slack.

The same deploy event can also create [Auto Monitors](https://app.struct.ai/managed-monitors) for that environment.

You can notify Struct in two ways:

1. **GitHub Deployments** — Struct listens for GitHub `deployment_status` events
2. **Webhook** — your deploy script posts to Struct with a **deployment key**

Use GitHub Deployments when your pipeline already creates them (GitHub Actions `environment:`, or GitHub's Deployment API). Use a webhook when it does not — for example a custom roll script, or canary then full in two named environments.

<Tip>
  In the app: **Monitors → Deployment audit** to create an audit, or **Auto Monitors** to pick which environment counts as production.
</Tip>

***

## GitHub Deployments

Struct needs the GitHub App installed on the repository, with:

* Permission **Deployments: Read-only**
* Webhook subscription **Deployment statuses**

Existing installations must approve the added Deployments permission.

Your pipeline must create GitHub Deployment records for the environment you monitor. In GitHub Actions, set the job's [`environment:`](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idenvironment):

```yaml theme={null}
jobs:
  deploy:
    environment: production
```

You can also create and update deployments through [GitHub's Deployment API](https://docs.github.com/en/rest/deployments/deployments).

Jobs without an environment, and environments configured not to create deployment records, will not trigger Struct. `workflow_run` is not supported — finishing a workflow does not prove a SHA reached an environment.

In Struct, create the monitor with **GitHub Deployments** and pick the environment from recent history. The environment name must match GitHub's name exactly.

***

## Webhook

If your pipeline does not create GitHub Deployments, create the monitor with **Webhook** and type the environment name your script will send.

Create a deployment key in **Settings → Deployment Keys** (org admins), or from the Webhook option on the monitor form / Auto Monitors **some other environment** row. The secret is shown once. Do not put it in application code or commit it.

Then POST when a SHA reaches that environment:

```bash theme={null}
curl -X POST "https://api.struct.ai/api/deployments/" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/api",
    "sha": "abc1234deadbeef",
    "environment": "staging",
    "status": "success",
    "idempotencyKey": "staging-abc1234"
  }'
```

| Field            | Notes                                                                            |
| ---------------- | -------------------------------------------------------------------------------- |
| `repository`     | `owner/name` of the GitHub repo Struct should audit                              |
| `sha`            | Git SHA that reached the environment (at least 7 characters)                     |
| `environment`    | Must match the monitor / Auto Monitors environment **exactly**, including case   |
| `status`         | `success`, `failure`, or `error` (default `success`)                             |
| `idempotencyKey` | Your unique id for this reach. Retrying the same key does not create a duplicate |

Ingest keys (`pk-…`) cannot call this endpoint. The GitHub App still needs access to the repository so audits can compare SHAs and open PRs.

Canary then production is two POSTs: same SHA, two environment names, two idempotency keys.

<Note>
  Only terminal statuses are recorded. There is no `in_progress` / started event — post when the SHA has reached (or failed to reach) the environment.
</Note>

***

## Auto Monitors

Auto Monitors run when a change deploys to the environment you configured as production.

* If that name is one GitHub already deploys to, GitHub `deployment_status` events are enough
* If you choose **some other environment**, notify Struct with a deployment key as above

The name must match exactly either way.