---
type: types/instruction.md
name: publish-and-ci
description: How a stack change is published and how its CI run is waited for - the local checks first, tools/wikitool publish, reading the runs through the authenticated Gitea connection rather than curl, how long to wait, when to give up, and why a red run means the build phase is not over.
---
# Publish a stack change and wait for its CI run

The local checks cover what they cover on this machine; CI covers the same checks plus a full
`setup-instance.md` replay against a fresh `dist export` (`.gitea/workflows/ci.yml`). A green run
on the published commit is therefore the end of the checked stretch of a work package, not a
formality after it - which is why waiting for it belongs to the phase that wrote the code
(`stack-build`), and a red run sends the work back there rather than into the closing phase.

## When to run

- `stack-build`, every time it publishes - its last step.
- `stack-close`, when its own pull-through of a stale document publishes something of its own
  (that skill's step 3 says when).

## Steps

1. **Run the local checks, explicitly rather than assumed:**

   ```bash
   tools/wikitool docs verify
   tools/wikitool instructions verify
   ```

   plus the relevant `pytest` run in `tools/` ([testing-conventions.md](testing-conventions.md)).
   A red check here is fixed before anything is published.

2. **Publish with `tools/wikitool publish`.** The gates apply as everywhere (AGENTS.md § Gates);
   an exit 42 is shown to the user verbatim and waited on. When the changeset touches `tools/`,
   `types/`, `instructions/`, `AGENTS.md` or a `<stage>/CONTRACT.md`, `publish` prints a
   one-line note that CI is the last mechanical check still to come and that what follows it is
   covered by none. A push to `main` that moves `VERSION` additionally triggers a tagged release.
   **CI does the tagging** - a session never creates a tag, which is what keeps AGENTS.md
   invariant 5 intact.

3. **Wait for CI on the published commit, this way.** The push-triggered runs take about
   **4 minutes**; a push that moved `VERSION` to a suffix-free release adds about **1 minute**
   for the release job.

   - Read the runs for the published commit's SHA through the authenticated Gitea connection
     `ENVIRONMENT.md` lists (the Gitea MCP's `actions_run_read`, `list_runs`), right after
     `publish`, to get their ids. **Never anonymously via `curl`:** Gitea answers the Actions
     API with `401 token is required` even for this public repo.
   - Check again after about 4 minutes (5 with a release job), then once a minute.
   - **Give up after 15 minutes** and hand the open runs to the user by id and link, rather than
     waiting on.
   - Any shell loop that polls instead must **end on the first non-2xx status or missing field**
     and print the raw response. A loop that treats an error as "not finished yet" never ends;
     that happened in the #139 close-out.
   - Keep the polling out of the main context where the harness allows it - a background
     command or a fork - so a long wait does not fill the session with run listings.

4. **A red run is not waited past.** Read the failing job's log, fix the cause, and go back to
   step 1: this is still build work, whichever skill published. The phase that published ends
   only on a green run, and the issue stays open until there is one.