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

# CI and test suites

> Add repeatable stateful tests without leaking the control-plane key or leaving sandboxes running.

CI is the natural home for repeated Archal tests. Archal does not ship a
dedicated CI wrapper or generated workflow templates. The `archal-ci` skill
helps a coding agent fit the lifecycle into your existing runner. Review its
plan before allowing workflow edits.

## Start with one protected workflow

Use a manual, nightly, or protected main-branch trigger first. Do not expose an
Archal secret to code from an untrusted fork. Never use `pull_request_target`
for a workflow that checks out and executes pull-request code.

## Use a separate CI key

Do not reuse the coding-agent pairing credential. Create a CI key restricted to
the environments and lifecycle scopes the workflow needs. Store it in the CI
secret manager.

The test subprocess must not inherit `ARCHAL_API_KEY`. It should receive only
the provider URLs and short-lived headers returned for its sandbox.

## Cancellation-safe lifecycle

1. Derive an idempotency key from provider run ID, attempt, job, matrix values, shard, and the create-body hash.
2. Create with `--detach` so the sandbox ID is available before readiness.
3. Write the create response to a mode `0600` file without printing it.
4. Wait for readiness.
5. Mask and inject only returned provider connections.
6. Remove `ARCHAL_API_KEY` from the test subprocess environment.
7. Run the intended integration or eval suite.
8. Request teardown in an always-run cleanup step.
9. Preserve the original test failure separately from a cleanup failure.

The idempotency key must be 200 characters or fewer. Hash long identity fields
instead of truncating away the values that distinguish parallel jobs.

## Bound cost and concurrency

* create only the environments the job needs
* use one sandbox per independent job or shard
* keep the initial TTL close to the job timeout
* cap matrix parallelism below the workspace session limit
* do not enable automatic recharge solely for CI
* destroy as soon as the test finishes

Each ready environment costs \$0.10 per minute. A sandbox containing three
ready environments accrues three environment-minutes.

## Prove the integration before broadening it

The first CI canary should show:

* one provider-shaped read
* one explicit before-state snapshot
* one meaningful mutation
* one diff against that snapshot
* one reset to the declared baseline
* durable teardown acceptance
* final destruction when the runner remains available

## Current limitations

* There is no verified GitHub Actions, GitLab CI, Buildkite, or CircleCI scaffold yet.
* CLI create, wait, status, and renew responses contain scoped credentials. Capture them in
  mode-`0600` files, mask returned credential values, and do not print them.
* Evidence export is metadata-only and does not include raw request or state payloads.
* Renewal rotates provider credentials, so long jobs must refresh their clients.
* Runner loss relies on TTL and orphan reconciliation after the process disappears.

These limits are reasons to begin with a narrow protected workflow, not reasons
to hide cleanup or cost behavior from the user.