Skip to content

architecture workflows

github-actions[bot] edited this page Nov 8, 2026 · 10 revisions

Workflows

The craft loop on GitHub (.github/workflows/). A workflow only says when and in which order; every step longer than one command is a script in scripts/workflows/, run as task workflows:<name> -- <arguments>, so it can be read and run by hand on its own. What the loop decides is bos flow of this checkout, reading .github/bos.json. Decisions Q10, Q11 and the owner's routine (changelog phase 2). Every workflow can also be started by hand (workflow_dispatch).

Names

A file name says what the workflow is and when it runs; its name: says the same in the Actions tab. Three families (owner's inquiry, phase 2):

  • checks-*: the checks, and when they run;
  • loop-*: the craft loop's stations (revision, master) and the by-hand step;
  • <registry>-<kind>-publish: one publishing target each.

The routine, on GitHub

flowchart LR
  dev["dev/&lt;name&gt;"] -->|merge, push| development
  development -->|push: checks-on-push-changed-parts| development
  development -->|agent stops: push| revision
  revision -->|loop-revision-…: checks, authors, bump| development
  revision -->|loop-revision-…: opens the PR| master
  master -->|loop-master-release-and-publish| out["tag · GitHub release · npm ×2 · images · docs · webhooks"]
  out -->|master back| development
Loading
Workflow Runs on Does
checks-reusable-set.yml called by the others; by hand: all one job per check: types, lint, tests, build (code), docs (locked MkDocs --strict, lock/export consistency and its regression tests), dependencies (npm audit at high severity), package (packs, installs, runs bos), commits (commitlint over a range)
checks-dependency-health.yml weekly on the default branch; by hand; image/config PRs full checks on schedule/by hand, including audit and docs consistency; builds and smoke-tests the container, without publishing
checks-on-push-changed-parts.yml push to development, dev/** only the parts the push touched: code, docs, or both (a new branch: both)
checks-on-pull-request-then-automerge.yml pull request into a station, opened by a person every check, the commits of the pull request too; then bos flow automerge (a pull request into master waits for a person)
loop-revision-bump-checks-pull-request.yml push to revision every check (the commits since master too); bos project authors (.github/AUTHORS); bos flow bump revision (the minor, once the line v<X.Y>.* is released); the release nightly moves to revision with the package's file; what it committed is pushed to revision and merged into development; then the pull request revision → master is opened (or the open one follows)
loop-master-release-and-publish.yml push to master checks; bos flow bump master (the patch, only for a released version: a hotfix); tag v<version> and GitHub release (a full release since phase 2 closed; a pre-release with PRERELEASE: "true", Q7); then Discord/Telegram; the package's file into the release, the release latest moved to it; the publish workflows, Read the Docs, the wiki, social media; master back into development; the BOS workshop called
npmjs-npm-package-publish.yml called by the release; a GitHub release made by a person; by hand npm publish --provenance to npmjs.org, next for a pre-release
github-npm-package-publish.yml called by the release; by hand the package on GitHub Packages as @sarverott/blacksmith-organization-system (it takes scoped names only), pre-releases under next
docker-container-publish.yml called by a full release; by hand the image of the Dockerfile on Docker Hub: <version>, <major>.<minor>, latest
github-container-publish.yml called by a full release; by hand the same image on ghcr.io/sarverott/blacksmith-organization-system
mirrors-propagate-and-status-badges.yml push to development, by hand every branch and tag to each mirror of .github/bos.json (mirrors.to), deletions too; a status badge per place on the branch badges; a failed mirror never fails the run
loop-next-pull-request-by-hand.yml by hand only bos flow next-pr <branch>: the full loop revision → testing → releasing → master, not driven yet

A push made by a workflow with its own token starts no other workflow, so the bumps and the merges back into development do not loop; for the same reason the pull request revision → master, opened with that token, starts no checks of its own: the revision workflow ran them before opening it and its description links that run. After the revision or the release workflow ran, pull development.

Releases that move

Besides one release per version (v<X.Y.Z>), three tags move, each with a GitHub release that follows it (never GitHub's "Latest": that stays the newest versioned release). Names are drafts (owner, Q12).

Tag Moves to When
nightly revision, a pre-release with the package's .tgz (not on npm) every push to revision
latest the last published release, with its .tgz every release
stable [TODO] what passed the tests of deployment and of the projects that depend on it, on releasing once the full loop runs

Container images are made only for a full release (not a pre-release): every release since phase 2 closed (Q7). "Stable LTS" is open: BRAINSTORM Q12.

Mirrors

The source is this GitHub repository; .github/bos.json (mirrors) lists where it is copied: gitea.com, gitlab.com, bitbucket.org, sr.ht. Every branch and tag is pushed to each (--prune: a branch deleted here goes there too), so a mirror's default branch must be one of ours (master), not a host's own main.

Each place has a badge, a shields.io endpoint read from the branch badges (one commit, force-pushed, never merged): github.com source: 200 OK, gitea.com mirror: 200 OK, 404 NOT_FOUND when the page is missing, 403 FORBIDDEN when the update failed (or its secret is missing), other HTTP statuses as they come.

It syncs on a push to development, where the work lands, and by hand; what the loop moved meanwhile (revision, master, tags) goes with that sync. A mirror that fails never interrupts the work: its badge shows 403 FORBIDDEN, the run logs an error, and the run passes.

Mirrors only receive. Nothing publishes from them (no Read the Docs, npm, images): releasing and publishing stay on GitHub. Their own platforms' releases come later, with each platform's integration. Each mirror runs only the checks on its own CI, on master and development: .gitea/workflows/checks.yml (with it Gitea ignores .github/workflows/), .gitlab-ci.yml, bitbucket-pipelines.yml, .builds/checks.yml (builds.sr.ht needs a paid sourcehut account).

Steps

Task (scripts/workflows/) Does Used by
changes which parts a push touched: code, docs checks-on-push-changed-parts
commits commitlint from a base, never before commitlint came in checks-reusable-set
package packs, installs into an empty project, runs bos checks-reusable-set
authors bos project authors, committed and pushed when .github/AUTHORS changed loop-revision-…
bump bos flow bump <station>, committed and pushed loop-revision-…, loop-master-…
merge-into a ref merged into a branch, pushed loop-revision-…, loop-master-…
pull-request the pull request <head> → <base>, unless one is open or nothing is new loop-revision-…
release tag v<version> and GitHub release, unless tagged loop-master-…
pack the package's .tgz, as npm gets it loop-revision-…, loop-master-…
rolling-release a tag (nightly, latest) moved and its release following, its files replaced loop-revision-…, loop-master-…
publish npm publish to npmjs (with provenance) or github (scoped), unless that version is there *-npm-package-publish
image-gate whether an image is made: a full release and a token *-container-publish
wiki the docs into the GitHub wiki, pushed loop-master-…
readthedocs the tag's version activated and built, latest rebuilt loop-master-…
mirrors every branch and tag to each mirror, a badge file per place mirrors-…
status-badges the badge files as the only commit of the branch badges mirrors-…
notify community (Discord, Telegram), social, workshop hooks loop-master-…

Secrets

Each outward call runs only when its secret is set; without it the step says so and does nothing. Publishing secrets live in the environment publish-env (repository settings → environments); the jobs that use them declare it.

Secret Where For
NPM_TOKEN publish-env npm: publishing to npmjs.org (npmjs-npm-package-publish.yml)
READTHEDOCS_API_TOKEN publish-env Read the Docs: activate and build the tag's version
DOCKER_HUB_TOKEN publish-env Docker Hub: pushing the image (docker-container-publish.yml); the user is the variable DOCKER_HUB_USERNAME, default sarverott (assumed)
SCALAR_API_TOKEN publish-env [TODO] not used yet: an API reference on Scalar, once BOS has an HTTP API (phase 4)
MIRROR_GITEA_TOKEN publish-env gitea.com: an access token with write:repository, pushed as the user Sarverott
MIRROR_GITLAB_TOKEN publish-env gitlab.com: a project (or personal) access token with write_repository - a fine-grained one needs the project permission Code: Push - user oauth2
MIRROR_BITBUCKET_TOKEN publish-env bitbucket.org: a repository access token with write (user x-token-auth), or an Atlassian API token ATATT… with write:repository:bitbucket (user x-bitbucket-api-token-auth, chosen by the prefix)
MIRROR_SOURCEHUT_SSH_KEY publish-env sr.ht: a private SSH key whose public half is in the sourcehut account (sr.ht takes pushes over SSH only)
(none) GitHub Packages (npm and ghcr.io) use the workflow's own token
WIKI_TOKEN repository a token that can push the wiki; without it the workflow's own token is used (it worked for v1.0.0)
DISCORD_WEBHOOK repository a Discord channel's webhook URL: the dev community
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID repository a Telegram bot and the chat it writes to
SOCIAL_WEBHOOK repository one webhook for social media, receives {event, repository, tag, url} ([TODO]: which media)
BOS_WORKSHOP_HOOK repository the listening BOS workshop, receives {event, repository, tag, sync} ([TODO]: BOS has no listener yet)

Read the Docs also builds every push by its own webhook, without a secret.

Dependency maintenance

.github/dependabot.yml targets development: one Monday minor/patch group per ecosystem (npm, uv docs, Actions and Docker). Majors remain separate; Node 25.x is excluded because it is End-of-Life. Version PR limits are three per ecosystem, four for npm while three blocked updates need room beside a routine group. Security PRs have GitHub's separate limit and default-branch handling. There is no Compose manifest to update. Dependabot reads policy from master; integration into development and revision prepares it, and the owner's release merge activates it.

For a batch, inventory all bot PRs and exact heads, inspect reviews/checks and actual callers, consolidate overlapping locks, and leave incompatible upgrades open with evidence. npm ci, task check, npm run build, task workflows:package, npm audit --audit-level=high, task docs:check-lock, task docs:test-lock and task docs:build verify a candidate. Exercise affected behaviour for majors. task docs:lock regenerates both docs artifacts; the check never repairs them. Close superseded PRs only after verifying the landed versions remotely. Follow the contributor branch and revision routine; no branch-protection bypass or unattended dependency approval is added.

Round evidence and remaining blockers: Joker's notes.

Clone this wiki locally