# NotusCI for agents `verify` runs this repository's GitHub Actions workflow on your committed and uncommitted changes in a clean Linux container and returns typed JSON. Set up with `npx -y notusci@latest init` (see https://ci.notusworks.com/llms.txt). ## CLI Run as `npx -y notusci@latest COMMAND`; `notusci help` prints this list. ```text notusci init [--scope SCOPES] [--no-mcp] [--billing] notusci billing [--repo OWNER/REPO] [--timeout SECONDS] notusci doctor notusci login [--scope SCOPES] notusci logout notusci whoami notusci repos notusci token list notusci token revoke ID notusci target set [--repo OWNER/REPO] [--file TARGET.json] [--auto-promote on|off] [--auto-release on|off] # provider token from $DIGITALOCEAN_TOKEN notusci secret set NAME [--repo OWNER/REPO] # value on stdin only notusci secret list [--repo OWNER/REPO] notusci secret rm NAME [--repo OWNER/REPO] notusci verify [--workflow PATH] [--timeout SECONDS] [--no-reuse] notusci wait ID [--repo OWNER/REPO] [--timeout SECONDS] notusci failures ID [--repo OWNER/REPO] notusci ship ID [--repo OWNER/REPO] notusci approve ID [--repo OWNER/REPO] notusci repo set [--repo OWNER/REPO] [--settings JSON|@FILE] [--push-workflow PATH|--off] [--image-from-workspace JSON|--image-from-dockerfile] notusci api METHOD PATH [--data JSON|@FILE] notusci migrations list [--repo OWNER/REPO] notusci migrations approve MANIFEST_DIGEST --push ID --reason TEXT [--repo OWNER/REPO] [--force-destructive] notusci search-logs ID --query LITERAL [--limit COUNT] [--repo OWNER/REPO] notusci rerun-failed ID [--timeout SECONDS] notusci --version ``` - `init`: signs in, checks the App is installed, picks the workflow and registers the MCP server in Claude Code, Cursor and Codex. Each run returns within 90 seconds; rerun it until `status` is `"ready"`. `action_required` carries `action.url` and `action.code` for the human. When GitHub asks which repositories, recommend **All repositories**: new repositories then work without another visit. - `doctor`: read-only. Prints `{ ready, checks: [{ name, ok, code?, next? }] }` for `git_repo`, `login`, `app_installed`, `workflow` and `mcp`. - `login`: forces a new browser approval. Returns after approval, or `pending` after 90 seconds. - `logout`: revokes the token and deletes `~/.config/notusci/auth.json`. - `verify`: the base is the newest commit of `HEAD`'s history that is on GitHub (an `origin` remote-tracking branch); NotusCI downloads it from GitHub. Only what differs from it is uploaded: unpushed commits, staged and unstaged changes, and untracked files that are not ignored, at most 64 MiB, 20,000 paths and 32 MiB per file. Ignored files are never uploaded. The checked-out source can be up to 2 GiB and 200,000 files. Waits up to `--timeout` (default 540 s), then prints the current result. Use a command timeout of at least 10 minutes. - `whoami`: prints `{ user, scopes, repos, installUrl }`. `repos`: prints `{ user, repos, installUrl }`, as `ci_repos` returns. `--version` (or `version`): prints `{ version }`; needs no repository or login. - `wait ID`: waits on a verify or push ID until `ready`. `ship ID`: ships a successful push. - `failures ID`: for a verify or push ID, prints `{ schemaVersion, verifyId, repo, ready, conclusion, tests?, refusal?, debug?, ingestion, failures, build? }`; `build` is `{ failedPhase, error }` when a push's image build failed. For a GitHub run ID it prints the run's jobs and failures. - `search-logs ID --query LITERAL`: searches receipt-referenced logs for a case-sensitive literal; `--limit` 1–100, default 20. - `rerun-failed ID`: after fixing the code, verifies your current working tree with the failed verify's workflow. The result links it as `rerunOf` with `relationship: "retry"` (same source) or `"correction"` (changed source). Run it from the repository; waits like `verify` (default 540 s). The failed verify must be in the same repository (otherwise `not_found`), finished and not `success` (otherwise `not_rerunnable`). - `approve ID`: approves the outside contributor of a pull request run that waits with `approval.status: "required"`, once per contributor for the account, and queues their waiting runs. Prints `{ approved: { id, login }, queued }`; `not_found` means no waiting run has that ID. Approve only when the human asks: their code then runs with internet access, billed to the owner. - `secret set NAME`: stores a repository secret for `${{ secrets.NAME }}`, reading the value from stdin only (`printf %s "$VALUE" | notusci secret set NAME`); it refuses a terminal. `secret list` prints names and update times, never values; `secret rm NAME` deletes one. Needs `ship:prod` to set or delete, `read` to list. See [Workflows](#workflows). - `repo set --push-workflow PATH|--off`: turns NotusCI push and pull request runs on with that workflow (or `.ts` pipeline), which must be on the default branch, or off. Needs `ship:prod`. - `repo set --settings '{"maxConcurrentRuns":1}'`: lets only one push, pull request or agent verify from this repository occupy an account slot at a time. `2` allows both slots and `null` inherits the account limit. A queued receipt reports `queueReason` when a repository or account concurrency limit blocks it. - `repo set --image-from-workspace JSON`: builds each push's image from what its passed workflow left in the workspace instead of reinstalling and recompiling in the Dockerfile, e.g. `'{"root":"/usr/src/app","stages":{"prod-deps":["node_modules"],"build":["dist"]}}'`. Each named stage (not the final one) is replaced by those workspace paths under `root`; `node_modules` is pruned to production dependencies. The rest of the Dockerfile builds as before. A build that can start beside the steps still builds from the Dockerfile there (`build.startedWithSteps: true`), because it is ready first. When the workspace can't be used safely (a path missing, a pnpm or Yarn PnP layout, a native file built on install that the runtime image can't load), the Dockerfile builds the image; the push's `build.from` and `build.fallback` say which and why. `--image-from-dockerfile` turns it off. Needs a ship target and `ship:prod`. - `repo set --settings JSON|@FILE`: sets any repo settings by name, e.g. `'{"imageFromWorkspace":null}'`, including ones newer than this CLI. See [Settings and hints](#settings-and-hints). - `api METHOD PATH [--data JSON|@FILE]`: calls any NotusCI API path (`PATH` starts with `/`, query string allowed) with the saved login and prints the JSON response, like `gh api`. Use it for an API feature the CLI has no command for yet, instead of reading the token out of `auth.json`. Errors are the usual `{ error, code, next }`. - `--scope`: comma-separated; default all four, `read,verify,ship:staging,ship:prod`. `--repo` defaults to the `origin` remote. - `target set --auto-promote on|off`: see [Shipping](#shipping-and-production-approval). Omitted, the target keeps its current setting. ### Tokens on other machines and in CI The CLI reads `NOTUSCI_TOKEN` and `NOTUSCI_URL` before `~/.config/notusci/auth.json`, so a machine with them set needs no login and no `auth.json`. In CI, store a token as a secret named `NOTUSCI_TOKEN`. On another machine, set `NOTUSCI_TOKEN` to an existing token, or run `init` there once to approve a new one. `notusci token list` shows your tokens; `token revoke ID` ends one. ## Output and errors Every command prints one JSON object on stdout. `action_required` and `pending` are not errors and exit 0. On error the CLI prints `{ "error", "code", "next" }` on stderr and exits 1. If `next` is a command, run it; otherwise tell the human `error`. HTTP errors have the same `error` and `code` fields. | Code | What to do | |---|---| | `not_logged_in` | Run `npx -y notusci@latest init`. | | `app_not_installed` | Run `npx -y notusci@latest init`; the human must install the NotusCI GitHub App on this repository. | | `not_account_owner` | Tell the human another GitHub user owns this account on NotusCI. | | `workflow_required` | Run `verify --workflow PATH` with one of `candidates`. | | `missing_scope` | Run `npx -y notusci@latest login --scope SCOPES` with the `scopes` given. | | `cap_reached` | Tell the human the monthly limit is reached and when it resets. Do not retry. | | `payment_required` | The trial is used up. On a deployment with billing enabled, run `notusci billing`; current production billing is disabled, so stop and report the limitation. | | `billing_unavailable` | Billing setup is disabled on this deployment. Do not collect payment details or repeat Checkout attempts. | | `migration_approval_required` | The push adds or changes migrations. See [Migration approvals](#migration-approvals). | | `destructive_migration` | Stop and tell the human; only they may approve with `--force-destructive`. | | `already_shipped` | This push already shipped and stopped at staging. Ship a newer push. | | `not_rerunnable` | The verify is unfinished or succeeded. Wait for it, or start a new `verify`. | | `base_unavailable` | No commit of `HEAD`'s history is on an `origin` remote-tracking branch. Push the branch (`git push -u origin HEAD`), or `git fetch --deepen` in a shallow clone, then retry. | | `too_large` | The changes are over 64 MiB or 20,000 paths, or a changed file is over 32 MiB. Commit and push the large files, then retry. | | `server_outdated` | The NotusCI server predates diff-only verify. Tell the human. | | `unknown_setting` | Use one of `valid`; `notusci api GET /api/settings` describes each. | | `source_required` | `ci_rerun_failed` without new source on a CLI-started verify. Pass `sha`/`overlay`, or run `notusci rerun-failed ID` from the working tree. | ## Billing availability New accounts get a 300-minute trial. Live billing is not enabled on the current production deployment. CLI 0.1.2 and later include `billing` and `init --billing`. On a deployment configured for billing, `billing` returns a first-party action URL and comparison code, then waits for signed webhooks to confirm readiness. Show the URL/code to the owner and let them complete Stripe-hosted Checkout. Agents never request or enter card data. A success redirect alone is not readiness. Rerun the command until it returns `ready`, then retry the original verification. A disabled deployment returns `billing_unavailable` without creating Checkout. ## Verify result A verify submission (`POST /api/verify/v2` or `/api/agent/verifies`) answers with a `Server-Timing` header: `token` and `tree` (GitHub calls for the snapshot hint, 0 when cached), `hint`, `upload` (the source to storage) and `accept` (queueing). A repeated idempotency key answers from the queue without uploading again. The fields an agent needs from `verify`, `wait` and `failures`: - `verifyId`: pass it to `wait` and `failures`. - `ready`: `false` while running. Run `wait VERIFY_ID` until it is `true`. - `conclusion`: `"success"`, `"failure"` or another GitHub conclusion; `null` until ready. - `failures`: `[{ kind, message, file?, line?, test?, excerpt }]`. `kind` is `node-test`, `junit`, `typescript` or `unparsed` (an `unparsed` entry carries the log tail in `excerpt`). Show the human `file`, `line` and `message`. - `steps`: ordered named steps with conclusion, exit code, duration and optional reason/view. A step with `reuse` was skipped because its declared inputs are unchanged since push `reuse.sourceVerifyId`; its log is in that push. - A retried step has two `attempts` with raw `outcome`, `exitCode` and `durationMs`. When the corresponding log frame is retained, `logStart` and `logEnd` give its UTF-8 byte range. Retries share the original workflow deadline and preserve workspace changes. The run omits combined test counts and JUnit evidence when it retries. - A step that failed with YAML `continue-on-error: true` has `outcome: "failure"` and `allowedFailure: true`. Its effective `conclusion` remains `"success"` and the receipt keeps the exit code and failure evidence. - `reuse` carries `status`, `ran`, `reused` and `savedMs`. Same-repository PRs can reuse declared steps from executed, secret-free pushes to the current default branch. PRs never write history, and the post-merge push executes the checks. A whole-result push hit includes the original push and each reused step. The saved time is the original step duration. - `tests`: `{ total, passed, failed, skipped }` from JUnit reports, or from the `node --test` summary when there are no JUnit totals. Older receipts may omit this field; missing is not zero. - `rerunOf`, `relationship`: set on a rerun; `relationship` is `"retry"` for the same source, `"correction"` otherwise. - `timing.completedAt`: set once the result is terminal (`ready`). - `timing.phases` (pushes and PRs): where the run's time went, in milliseconds from `startedAt`, in order: `startMs` (container start), `prepareMs` (source, actions), `runMs` (steps), `resultsMs`, `packageMs`, `stopMs`, `imageMs` (build and publish after the steps), `settleMs`; `errorMs` ends a run that failed. They add up to the run. `timing.engine` splits the engine's own calls: `sourceMs`, `actionsMs`, `installMs`, `hashMs` (prepare) and `checkMs`, `stepsMs`, `reportsMs` (run). - `snapshot.cacheHit`: the dependency environment was restored from an earlier verify. Separate from `cache`. - `cache.status`: `"hit"` means an identical successful verify or opted-in push's whole result was reused (steps skipped, no compute); `"miss"` or `"ineligible"` otherwise. Never `"pending"` once ready. - `refusal`: `{ code, reason }` when source, workflow or policy was refused. Show the reason; do not infer a test failure from an empty log. `base_not_found`: GitHub doesn't have the base commit; `git push`, or `git fetch --prune` so the CLI picks a pushed ancestor, then verify again. `source_too_large`: the checked-out source is over 2 GiB or 200,000 files. - `debug`: availability and expiry for an opted-in failed filesystem; no snapshot handle is public. - `failures[].comparison`: retained evidence for a `junit` test failure. `flaky: observed` means both pass and fail were seen for the same immutable source. `not_observed` refers only to complete retained evidence; `unknown` means evidence is incomplete. `newSinceGreen` is true for the first observation in a proven red streak, false for a repeated observation, and null when the green boundary or intervening evidence is insufficient. Evidence IDs support the claim; these fields do not predict future flakiness. - `errorCode`: `"cap_reached"` or `"payment_required"` when usage limits stopped the verify. - `build.failedPhase` and `build.error` (pushes): the image build failed in `prepare`, `build`, `store` or `publish`, and why. The push's `conclusion` is `"error"`; its passed steps keep their `logs` and `ingestion`. A built image may be up to 2 GiB; a larger one fails with `error` naming its size. - `hints`: on a push, rarely, `[{ code, message, mcp: { tool, input }, cli, api: { method, path, body }, docs }]`: a feature that would have helped this push, with the exact call. See [Settings and hints](#settings-and-hints). ## MCP Server: `https://notusci-api.binh-08d.workers.dev/mcp` (streamable HTTP). `init` registers it with your CLI token; clients without that entry sign in with OAuth. | Tool | Scope | Does | |---|---|---| | `ci_repos` | `read` | Your repositories and the App install URL. | | `ci_wait` | `read` | Waits on a verify or push ID. | | `ci_failures` | `read` | Typed failures for a verify or push ID. | | `ci_verify` | `verify` | Starts a committed verification with an optional bounded overlay. | | `ci_rerun_failed` | `verify` | Retries or corrects a terminal failed verification. | | `ci_search_logs` | `read` | Searches receipt-referenced logs for a case-sensitive literal. | | `ci_exec` | `verify` | Runs a bounded command in an opted-in failed filesystem. | | `ci_ship` | `ship:staging` | Ships a push; returns the ship result with `approval`. | | `ci_migrations_approve` | `ship:prod` | Approves a refused push's migration manifest, as `notusci migrations approve` (never destructive ones). | | `ci_repo_set` | `ship:prod` | Sets repo settings: `{ repo, settings: { NAME: VALUE } }`, any setting at `/api/settings`, as `notusci repo set --settings`. | | `ci_approve` | `verify` | Approves the outside contributor of a waiting pull request run, as `notusci approve`. | A tool outside your scopes returns `missing_scope`. Use an already-available MCP connection directly; changing a client's MCP configuration may require a new session. The CLI remains suitable for local diffs larger than MCP limits. ### Verify, retry and inspect ```text ci_verify({ repo, workflow?, sha?, overlay?, idempotencyKey, debugOnFailure?, reuse? }) ci_rerun_failed({ repo, failedVerifyId, sha?, overlay?, idempotencyKey, debugOnFailure?, reuse? }) ci_search_logs({ repo, runId, query, limit? }) ci_exec({ repo, failedVerifyId, argv, idempotencyKey }) ``` Use a stable 8–128 character idempotency key containing letters, digits, `_` or `-` for each intended verification or exec. Repeating the same request/key returns its existing receipt; changing its input under that key is a conflict. Repository ownership is checked for every operation. Without `sha`, `ci_verify` resolves the default-branch head once. An overlay requires an explicit 40-character lowercase commit SHA. Its shape is `{ files: [{ path, mode, dataBase64 }], deletions: [] }`, with modes `100644`, `100755` or `120000`. MCP allows at most 256 changed/deleted paths, 2 MiB decoded content and 3 MiB request JSON. Use CLI `verify` for larger local changes. Wait for the returned verify ID using `ci_wait`. `ci_rerun_failed` requires a terminal failed verification in the same repository and retains its workflow. Without new source it retries that exact source of an MCP-started verify; for a CLI-started verify it returns `source_required`, so pass `sha`/`overlay` or run `notusci rerun-failed ID` from the working tree. With new source it records a correction when the identity changes. It runs a full verification, not only the failed steps. Transport retries retain the same idempotency key. Log search is literal and case-sensitive. Its default limit is 20, maximum 100; it reads at most 8 MiB and returns bounded excerpts with line/step context. Respect `truncated`; no match in an incomplete search does not prove absence. For debug exec, submit the verification with `debugOnFailure: true` and check `debug.status` is available. The 15-minute eligibility window does not extend when used. `argv` runs directly, without an implicit shell, for at most 60 seconds; it accepts 1–64 strings and at most 16 KiB encoded. Output is bounded to 1 MiB combined. The restored filesystem has no outbound network or provider credentials. Each command starts from the same immutable failed filesystem; changes do not persist into later commands. Commands share the account queue and are metered. `debug_unavailable` means no usable lease; do not recreate an exec with a new key to retry an ambiguous command. ### Snapshot performance Eligible dependency snapshots and diff uploads can reuse an installed environment across source edits. The accepted warm fixture completed in 5.32 seconds; this is a measured fixture result, not a latency guarantee. Eligible workflows use `checkout`, `setup-node`, `setup-go` and `pnpm/action-setup` with literal inputs and `pnpm install --frozen-lockfile` steps (workspaces and several lockfiles included); other workflows, including yarn and npm installs, use whole-source fallback. Per-step file-read skipping is not enabled: a source change can still rerun all steps. ## Settings and hints New features reach agents when the API deploys, before any CLI release or MCP reconnect. - `GET https://ci.notusworks.com/api/settings` (no login) lists every repo setting with a one-line description, an example and what `null` does. The server validates with the same table. - Set any of them with `ci_repo_set({ repo, settings: { NAME: VALUE } })`, `notusci repo set --settings '{"NAME":VALUE}'` or `PUT /api/repos/OWNER/REPO/settings` with `{ "NAME": VALUE }`. All need `ship:prod`. Every value is checked before any is saved; an unknown name returns `unknown_setting` with `valid`. - `notusci api METHOD PATH [--data JSON|@FILE]` reaches any API path with the saved login. - A push receipt's `hints` say when a feature would have helped that push, with the exact MCP, CLI and API call. There are two. `image_from_workspace` appears when the Dockerfile spent at least 10 s reinstalling or rebuilding Node stages with `imageFromWorkspace` off. Its stages, `root` and paths are guesses from the build steps; check them against the Dockerfile before setting it. `test_reports` appears when a step looks like a test run but no test results were read; its `cli` is the line that makes that tool write JUnit (see [Test results](#test-results)), and it has no `mcp` or `api` form. - A Dockerfile build receipt can report `build.cache.reason: "base_image_changed"` and the message `base image changed` when a warm cache was imported, steps ran, and a base tag resolved to a different digest than in the saved cache. `build.cache.changedBases` lists each observed `reference`, `previousDigest` and `digest`. Cache transport can still report `status: "warm"`. These docs are served by the API itself, so they always match it. ## Test results Receipts, `ci_failures` and Insights read JUnit. With no workflow change, NotusCI reads: - **Jest** and **Mocha**: a hook loaded through `NODE_OPTIONS` records each run in the runner's main process. Output, reporters and exit codes are unchanged. - **Vitest 2–5**: the same hook adds a silent reporter beside Vitest's own in its main process, on Node 22.15+, 23.5+ or 24+. Elsewhere, or if the hook can't apply, NotusCI reads Vitest's `FAIL` blocks: the receipt lists the failing tests, `tests.partial` quotes Vitest's own summary, and the run has no inventory. - **`node --test`**: its `--test-reporter=junit` file, or the spec/TAP summary in the log. - **pytest** and **`python -m unittest`**: `/opt/notusci/python` is appended to `PYTHONPATH`. In a pytest or unittest process only, a silent plugin records the run. It doesn't load under `python -E`/`-I`, when a step replaces `PYTHONPATH`, or when an earlier entry has its own `sitecustomize`. - **Go**: what `go test` prints, with or without `-v`, or its `-json` events. Without `-v` Go names only failing tests, so the receipt lists those and `tests.partial` says pass counts aren't available. Those failures still get new-since-green, but can't be seen flaky (no passes to compare); the run's other tests keep their comparison. Failures carry the file and line of the first `file_test.go:12:` message or the panic. - **Rust**: what `cargo test` (libtest) and `cargo nextest run` print, every binary and doctest; nextest gives durations. `cargo test -q` names only failures and is partial like Go without `-v`. Output that doesn't add up to libtest's or nextest's own totals (for example with `--nocapture`) isn't read. - **Maven Surefire/Failsafe**, **Gradle** and **cargo-nextest**: their default XML reports. - Any JUnit file a run step writes: `test-results.xml`, `junit.xml`, `*junit*.xml` and `TEST-*.xml` anywhere; everything under `target/surefire-reports`, `target/failsafe-reports`, `target/nextest`, `build/test-results`, `test-reports` and `reports`. Dependency, VCS and virtualenv folders are skipped. At most 64 files and 6 MiB per run. Other tools need one line that writes JUnit. A receipt's `test_reports` hint names it: | Tool | Line | |---|---| | gotestsum | `gotestsum --junitfile junit.xml` | | Go, when its output can't be read | `go test -v ./... 2>&1 \| go run github.com/jstemmer/go-junit-report/v2@v2.1.0 -set-exit-code -iocopy -out junit.xml` | | Rust, when its output can't be read | `cargo nextest run --profile ci` with `[profile.ci.junit] path = "junit.xml"` in `.config/nextest.toml` | | RSpec | `rspec --format progress --format RspecJunitFormatter --out junit.xml` (gem `rspec_junit_formatter`) | | PHPUnit | `phpunit --log-junit junit.xml` | | .NET | `dotnet test --logger "junit;LogFilePath=junit.xml"` (package `JunitXml.TestLogger`) | | Swift | `swift test --xunit-output junit.xml` | | Bun | `bun test --reporter=junit --reporter-outfile=junit.xml` | | Deno | `deno test --junit-path=junit.xml` | | CTest | `ctest --output-junit junit.xml` | | ExUnit | `mix test --formatter JUnitFormatter --formatter ExUnit.CLIFormatter` (package `junit_formatter`) | ## Workflows One job per workflow, on `runs-on: notusci`, `ubuntu-latest` or `linux`. Supported: `${{ }}` expressions (contexts `github`, `env`, `matrix`, `steps`, `secrets`, `runner`, `job`, `vars`; functions `success`, `always`, `failure`, `cancelled`, `contains`, `startsWith`, `endsWith`, `format`, `join`, `toJSON`, `fromJSON`) in `if`, env values, `run`, `with` and step `name`; step `id` with `GITHUB_OUTPUT`; `continue-on-error`; workflow, job and step `env`; `defaults.run`; and a single-axis `strategy.matrix` (combinations run one after another). Actions: `actions/checkout`, `actions/setup-node`, `actions/setup-go`, `pnpm/action-setup`. Anything else is refused with `refusal.reason` naming the feature and its line, e.g. `line 30: unsupported expression function hashFiles`. A local verify evaluates as a `push` to the default branch with no secrets: `${{ secrets.NAME }}` is `''`, as on GitHub for fork pull requests. Only push runs for the configured branch receive repository secrets; their values and every `::add-mask::` value are shown as `***` in logs, reasons and reports. ### Reusing step results A `run:` step without an `id` can declare the paths its result depends on: ```yaml - name: Test run: node --test working-directory: apps/api env: NOTUSCI_INPUTS: apps/api packages/pipeline ``` A verify then skips that step when a push to the default branch passed it with the same inputs, the same earlier steps and the same environment. Every `package.json`, lockfile, `.nvmrc`, `go.mod`, `go.sum` and `go.work` is an input too. Only declare paths the step really depends on, and only for a step whose output no later step needs. Eligible same-repository PRs to the default branch can also reuse steps from fully executed pushes that ran without secrets. PRs never write history. The push after merge runs the checks again. For a local verify, `--no-reuse` or `reuse: false` runs every step. Owners can separately opt in to whole-result push reuse with `pushResultReuse` in [repository settings](https://ci.notusworks.com/api/settings). It applies to eligible direct no-op pushes whose tree, exact workflow, Verify image and secret set match a fully executed passed push. It requires a deterministic shell workflow and excludes release and build targets. ## Pull requests from forks A pull request from a fork by someone who is not a collaborator waits with `approval: { status: "required", user: { id, login } }` until the owner approves that contributor once, with `notusci approve RUN_ID` or `ci_approve({ repo, runId })`. Later pull requests from the same contributor run without asking. Agents approve only when the human says so. ## Scopes | Scope | Allows | |---|---| | `read` | wait, failures, logs, receipts, usage, repos; list and revoke own tokens | | `verify` | start verifies; approve outside contributors | | `ship:staging` | start a ship; it stops after staging | | `ship:prod` | a ship may continue to production, after human approval or by auto-promote; set ship targets | Tokens are minted only through the browser approval page. A token cannot mint another. ## Shipping and production approval Ship targets are set only with `notusci target set` or in the dashboard Settings, so provider tokens stay out of model context. There is no MCP tool for them. Each target has an auto-promote setting, on for new targets. With it on, a ship with `ship:prod` goes to production as soon as staging is healthy, or at once when there is no staging, and records `approval: { status: "approved", decidedBy: "auto-promote", decidedAt }`. The setting is read when the ship is submitted. Turn it off with `notusci target set … --auto-promote off` or in the dashboard Settings. With auto-promote off, a ship that may reach production enters `awaiting_approval` after staging is healthy, or at once when the target has no staging. `ship` and `ci_ship` return as soon as approval is pending, with `ready: false` and: ```json { "approval": { "status": "pending", "url": "https://ci.notusworks.com/dashboard/ship?repo=OWNER%2FREPO&id=SHIP_ID" } } ``` `approval` is `{ status, url, decidedBy?, decidedAt? }`; `status` is `pending`, `approved`, `rejected`, `expired` or `superseded`, and `decidedAt` is epoch milliseconds. 1. Show the human `approval.url`. They approve or reject in the signed-in dashboard, which shows the image digest, the production app and component, and `targetConfigDigest`. No token can approve. 2. After the human decides, run `notusci ship ID` or `ci_ship` for the same push again. It returns the same ship with the outcome; it does not start a new one. Rejection, a newer ship for the same repository (`superseded`), or 24 hours waiting (`expired`) end the ship as `failure` with no production change. A ship that ended `conflict` stopped because something outside it changed, for example a production baseline that fails provenance. After fixing the cause, `ship ID` for the same push admits a new ship that re-runs validation and provenance; the old receipt stays readable by its ship ID. Any other ship, running or finished, is returned as is. ### Auto-release With `notusci target set --auto-release on` (or the dashboard checkbox; off by default), every push to the default branch that succeeds with an image ships itself, exactly as `ship ID` would with `ship:prod`. The push receipt gets `release`, and its GitHub check summary gets a release line: - `submitted`: `shipId`, and `next` (`ship ID`) returns that ship and follows it. Each read of the receipt follows the push's newest ship: `submitted` while it runs, then `shipped`, `failed` (with `error`), or `conflict` (with `error`). After a conflict, fix the cause and run `next`: it admits a new ship that re-checks the target. - `waiting_migration_approval`: `next` is the approve command (see below). After approval, the newest waiting push releases itself. - `superseded`: a newer push released. An older auto-released ship that had not started ends as `failure` "superseded by a newer release". - `refused`: `error` says why. `off`: auto-release was turned off after the push started. Auto-promote still applies, and a destructive approval still waits for the human's browser approval. With both switches on, anyone who can push to the default branch deploys to production, so protect the branch. `--file` may be left out when only switches change. ### Migration approvals A push whose migration manifest is neither the production baseline nor approved is refused with `migration_approval_required`. The error lists `migrations.added`, `changed` and `removed` (paths under the target's migration root, compared with the newest healthy production ship, else the baseline), a `review` git diff command, and `next`, the exact approve command. 1. Read every listed file (`review`), check the live migration ledger read-only, verify staging, and confirm backup/recovery and that the previous image still works with the new schema. `changed` files that already ran will not run again. 2. Run `next` (or `ci_migrations_approve`) with that evidence as `--reason`, then `ship` the same push again. Approval is for that exact manifest digest and needs `ship:prod`. If an added or changed file's forward migration has `DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE` without `WHERE`, or TypeORM `dropTable`/`dropColumn`/`clearTable`, approval returns `destructive_migration`: an agent stops and tells the human. Only a human may rerun it with `--force-destructive`; that ship then waits for browser approval even with auto-promote on. The scan is a tripwire, not a safety proof. Up to 32 approvals are kept; the oldest one not deployed is dropped first. `migrations list` shows the baseline and approvals; `target set` keeps them unless its file has `migrations.approvals`, which then replaces the list. Without `ship:prod`, a ship ends after staging, and a ship for a target with no staging returns `missing_scope`. Asking for production on a push whose ship already stopped at staging returns `already_shipped`.