# Test before production

Production follows every merge unless you hold it. Use staging to try a change first.

Pick the option that matches when you want to test:

| You want to test | Use |
| --- | --- |
| A pull request, before merging | [Staging follows the pull request](#test-a-pull-request) |
| A merge, before production gets it | [Hold production, then release](#hold-production-while-staging-takes-a-merge) |
| One exact version, for longer | [Hold staging on a version](#hold-staging-on-a-version) |
| Uncommitted changes, through your own app | [`introspection dev`](#test-local-changes-through-your-app) |

**You need:** a deployed runtime ([Deploy your agent](/ship)) and a version ID from `introspection runtimes list --runtime <slug>`. Any version of the runtime identifies it. `runtimes pin` and `unpin` ask before they move staging; pass `-y` in scripts and CI.

## Test a pull request

1. Point staging at the pull request's preview build:

   ```bash
   introspection runtimes pin <version-id> --branch pr/42
   ```

   `--branch` takes `main` or `pr/<N>`.

2. Send it work:

   ```bash
   introspection tasks create --runtime support-agent -e staging --prompt "Refund order 1842?"
   ```

Staging moves to each new push on the pull request. When the pull request merges or closes, staging returns to the default branch on its own. To return earlier:

```bash
introspection runtimes unpin <version-id>
```

## Hold production while staging takes a merge

1. Pin production to the version it runs now ([Roll back a release](/ship/rollback#pin-production-to-a-version)).
2. Merge. Staging moves to the new version; production stays.
3. Test staging as above.
4. Unpin production. It moves to the newest good build.

## Hold staging on a version

`introspection runtimes pin <version-id>` (or `--sha <commit>`) moves staging to one version until the next merge or pull request preview. To hold it, pin a commit: **Pin staging → Pin to commit** in the dashboard, or the [API call for production](/ship/rollback#pin-production-to-a-version) with `staging` in its place.

## Test local changes through your app

```bash
introspection dev
```

Tasks your app creates in `development` now run your local files. It needs a runtime, and offers to create one when run interactively. See [Develop locally](/build/local).

## Verify

```bash
introspection runtimes get <version-id> -o json
```

`environments` lists where this version serves. `environment_ref` shows what each environment follows:

| `environment_ref` entry | Staging | Production |
| --- | --- | --- |
| None | The newest default-branch build; the next pull request preview takes it | The newest default-branch build |
| `main` (set by `pin --branch main`) | The newest `main` build; previews don't take it | — |
| `pr/42` | That pull request's newest preview, until it merges or closes | — |
| A commit SHA | Held on one version | Held on one version |

Then confirm a staging task ran the commit you expect:

```bash
introspection conversations list --lookback 1h --filter environment=staging \
  --filter recipe_git_commit_sha=<full-commit-sha>
```

## Limits

| Not supported | Do this instead |
| --- | --- |
| `runtimes pin` on production | The CLI steers staging only. Pin production in the dashboard or the API ([Roll back a release](/ship/rollback)). |
| Real user traffic on staging | Staging gets only the tasks you send. Run an [experiment](/improve/experiments) in production. |
| A staging task on an exact version | `tasks create --runtime-id <version-id>` pins a version only with `-e development`; staging runs whatever staging serves. |
| Moving running tasks | Pins affect new tasks only. |

Or ask your agent: "Point staging at pull request 42 and run three test tasks against it."

Test before production

Production follows every merge unless you hold it. Use staging to try a change first.

Pick the option that matches when you want to test:

You want to test	Use
A pull request, before merging	Staging follows the pull request
A merge, before production gets it	Hold production, then release
One exact version, for longer	Hold staging on a version
Uncommitted changes, through your own app	`introspection dev`

You need: a deployed runtime (Deploy your agent) and a version ID from introspection runtimes list --runtime <slug>. Any version of the runtime identifies it. runtimes pin and unpin ask before they move staging; pass -y in scripts and CI.

Test a pull request

Point staging at the pull request’s preview build:
```
introspection runtimes pin <version-id> --branch pr/42
```
--branch takes main or pr/<N>.

Send it work:


introspection tasks create --runtime support-agent -e staging --prompt "Refund order 1842?"

Staging moves to each new push on the pull request. When the pull request merges or closes, staging returns to the default branch on its own. To return earlier:


introspection runtimes unpin <version-id>

Hold production while staging takes a merge

Pin production to the version it runs now (Roll back a release).
Merge. Staging moves to the new version; production stays.
Test staging as above.
Unpin production. It moves to the newest good build.

Hold staging on a version

introspection runtimes pin <version-id> (or --sha <commit>) moves staging to one version until the next merge or pull request preview. To hold it, pin a commit: Pin staging → Pin to commit in the dashboard, or the API call for production with staging in its place.

Test local changes through your app


introspection dev

Tasks your app creates in development now run your local files. It needs a runtime, and offers to create one when run interactively. See Develop locally.

Verify


introspection runtimes get <version-id> -o json

environments lists where this version serves. environment_ref shows what each environment follows:

`environment_ref` entry	Staging	Production
None	The newest default-branch build; the next pull request preview takes it	The newest default-branch build
`main` (set by `pin --branch main`)	The newest `main` build; previews don’t take it	—
`pr/42`	That pull request’s newest preview, until it merges or closes	—
A commit SHA	Held on one version	Held on one version

Then confirm a staging task ran the commit you expect:


introspection conversations list --lookback 1h --filter environment=staging \
  --filter recipe_git_commit_sha=<full-commit-sha>

Limits

Not supported	Do this instead
`runtimes pin` on production	The CLI steers staging only. Pin production in the dashboard or the API (Roll back a release).
Real user traffic on staging	Staging gets only the tasks you send. Run an experiment in production.
A staging task on an exact version	`tasks create --runtime-id <version-id>` pins a version only with `-e development`; staging runs whatever staging serves.
Moving running tasks	Pins affect new tasks only.

Or ask your agent: “Point staging at pull request 42 and run three test tasks against it.”