chemenu/instructions/dev/publish-and-ci.md

type, name, description

type	name	description
types/instruction.md	publish-and-ci	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 - and, for a converter change, a green Converters run (step 3) - 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:

   tools/wikitool docs verify
   tools/wikitool instructions verify
   

   plus the relevant pytest run in tools/ (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.

   Converter changes have a second run. When the published commit touches the converter surface - tools/chemenu/filters/, tools/chemenu/commands/raw/derive.py or accept.py, tools/chemenu/tests/test_raw_derive*.py, tools/chemenu/tests/binary_formats.py, tools/requirements.txt or .gitea/workflows/converters.yml - the Converters workflow (converters.yml) starts by itself beside CI and derives the real documents of the private test corpus. It takes longer than CI (allow 10 minutes); wait for it the same way, with the same give-up time, and count a red run like a red CI run (step 4). Start it by hand (actions_run_write, dispatch_workflow on main) when only the private repository changed or when the commit reaches the converters only indirectly. A release without suffix runs the same steps as the first job of release.yml, which the release waits for.

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.