Skip to main content
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.