One CI and release pipeline for every moku package.
Reusable GitHub workflows pinned by tag, plus the moku-release CLI that installs them
into a project and runs a release. A project keeps two 20-line files and eight scripts;
everything else lives here, once. Not a build tool and not a framework — it calls your
package.json scripts and never the tools behind them.
Install · How it works · Workflows · Project checks · PR previews · Demos · CLI · The contract · Versioning · Scripts
bun add -d @moku-labs/ci
bun run release:setupsetup writes the two workflow files and the Dependabot files, adds the missing scripts,
does the first publish, registers the trusted publisher, applies the branch ruleset and
allows auto-merge. Run it again any time — it only does what is still missing.
Note
Status: 1.x, in use. All eight moku packages — core, common, web, worker, room,
system, ai, native — run package-ci.yml and package-release.yml from @v1, and each
has shipped a tokenless release with provenance through them. moku-release setup did every
one of those migrations live, including two first publishes behind 2FA.
Important
Two steps are yours alone. The CLI never handles a credential, and there is no NPM_TOKEN
anywhere — publishing is tokenless OIDC.
gh auth login
npm login- One copy of the pipeline. Eight packages had eight different
ci.ymland eight differentpublish.yml. A fix now lands here and reaches every project through the@v1tag. - Scripts are the interface, not tools. The workflows call
bun run lint, neverbiome. A project with special needs changes its own script, not the central YAML. - The CLI and its templates are one package.
moku-releasereadsexamples/andrulesets/from its own install. There is no second copy to drift. - No tokens. npm Trusted Publishing with
id-token: write. Build and publish run in separate jobs, so no dependency's postinstall ever sees the credential. - Not a dependency of your app. A dev dependency with zero runtime dependencies of its
own, so even
@moku-labs/corecan use it without a cycle.
flowchart LR
P["your project<br/>ci.yml · publish.yml<br/>8 scripts"] -->|"uses: …@v1"| W["moku-labs/ci<br/>reusable workflows"]
C["moku-release<br/>setup · doctor · release"] -->|writes| P
C -->|dispatches| W
W --> N["checks on the PR<br/>tag · GitHub release · npm"]
classDef u fill:#0b7285,stroke:#08525f,color:#fff;
classDef m fill:#1864ab,stroke:#0d3d6e,color:#fff;
class P,N u
class W,C m
release:setupwrites two thin callers into.github/workflows/.- Every PR runs
package-ci.yml: four jobs, reported asci / lint,ci / types,ci / test,ci / build. - Every merge to
mainrunspublish.yml, which callspackage-release.yml: check → tag → pack → publish. The version is always a patch.release waitwaits for it and verifies the version on npm. - A person runs
release minor, orrelease majorfor a milestone. It dispatches the samepublish.yml.
| Who releases | Version |
|---|---|
a merge to main |
patch, always |
| a person | minor |
| a person, for a milestone | major |
| Workflow | Called from | Jobs | Inputs (all optional) |
|---|---|---|---|
package-ci.yml |
examples/package/ci.yml |
lint · types · test · build · extra · preview |
runs_on, bun_version, validate, preview, extra |
package-release.yml |
examples/package/publish.yml |
check → release → package → publish |
release_type, publish, runs_on, bun_version, node_version, artifact_name, validate, extra |
app-deploy.yml |
examples/app/ci.yml |
validate → deploy to Cloudflare |
script names (lint_script, build_script, deploy_script, …) and two required secrets |
self-test.yml |
this repo only | actionlint over workflows and examples |
— |
package-release.yml outputs tag, version, prev_tag and artifact_name.
| Other file | What it is |
|---|---|
examples/package/publish.local-publish.yml |
Fallback: publish from the project's own job. Use it only if the central publish fails npm auth. |
rulesets/main.json |
Branch ruleset for main: PR only, no force-push, the four ci / … checks required. |
examples/dependabot.yml |
Dependabot config: one grouped PR a day for @moku-labs/* only. setup writes it to .github/dependabot.yml. |
examples/org/fleet.yml |
For the organization's .github repository. Every 15 minutes it runs moku-release fleet --markdown --deps and puts the table between <!-- fleet:start --> and <!-- fleet:end --> of profile/README.md. |
examples/package/dependabot-automerge.yml |
Turns on auto-merge for a Dependabot PR; the ruleset checks stay the gate. After the merge it dispatches publish.yml with patch, because a merge made by GITHUB_TOKEN starts no push run. A bump of devDependencies alone dispatches nothing: the published package is the same, and two packages that pin each other would release each other forever. setup writes it and allows auto-merge on the repo. |
Tip
A Layer-3 app copies examples/app/ci.yml and examples/dependabot.yml by hand and needs
a deploy script. An app merges Dependabot PRs by hand, because the merge runs the deploy.
The CLI sets up packages only.
A check the five contract scripts do not cover goes in extra: a JSON array of script names.
Each one is its own job, run after a build, and reported as ci / extra (check:bundle).
# .github/workflows/ci.yml
jobs:
ci:
uses: moku-labs/ci/.github/workflows/package-ci.yml@v1
with:
extra: '["check:bundle", "test:cli-e2e"]'| Rule | Where |
|---|---|
Give publish.yml the same extra, so a release waits for the same checks. |
caller publish.yml |
setup never replaces a thin caller that differs from the template. |
moku-release setup |
An extra job is not a required check until the ruleset of that repo names it. |
repo ruleset |
A check that needs its own matrix or a cron stays a separate workflow file. doctor and setup only look at ci.yml and publish.yml. |
the project |
A package may keep its version in git tags only. build and preview then seed
package.json from the latest v* tag before they pack. Nothing is committed.
Every pull request commit is published to pkg.pr.new by the preview
job. Nothing reaches npm and no token is in scope. The bot comments the install command on
the PR.
bun add https://pkg.pr.new/@moku-labs/core@42 # 42 = PR number, a commit sha works too| Rule | Where |
|---|---|
| The pkg.pr.new GitHub App must be installed on the repo. | once per org |
| The package repo must be public. The consuming project may be private. | pkg.pr.new |
A preview URL never reaches main: the lint job and doctor both refuse it. |
package-ci.yml, preview-deps |
preview is not a required check. Turn it off with with: { preview: false }. |
caller ci.yml |
demos.yml runs the moku demos (moku-labs/demos) against what a pull request builds, so an
engine or editor change that breaks a real game fails on its own PR.
demos:
needs: ci
if: github.event_name == 'pull_request'
uses: moku-labs/ci/.github/workflows/demos.yml@v1
with:
game: https://pkg.pr.new/@moku-labs/game@${{ github.event.pull_request.head.sha }}
tier: ${{ contains(github.event.pull_request.labels.*.name, 'demos:full') && 'full' || 'fast' }}| Input | Default | Meaning |
|---|---|---|
game, editor |
"" |
A version, a pkg.pr.new URL, or empty for each demo's own pin |
tier |
fast |
fast: bun run test on ubuntu. full: plus test:visual on macos-latest and test:editor |
demos_ref |
main |
demos branch when no paired branch exists |
paired_ref |
PR branch | demos branch with this name wins, for an intended break |
only |
[] |
JSON array of demo folders; empty = all |
| Rule | Where |
|---|---|
A demo is a folder whose package.json has "moku": { "demo": true }. |
demos repo |
The workflow only calls the demo's scripts with --engine / --editor; the demo's runner picks the package, as it does locally. |
demo runner |
A tracked file with /Users/, /home/… or ?? "../ fails the run. Paths are parameters. |
discover |
Checks to require: demos / fast; demos / full reports only on the full tier. |
rulesets |
| Pixels run on macOS: on Linux runners WebGPU loses its device. | visual-run |
Examples: examples/package/ci-with-demos.yml (label demos:full) and
examples/package/demos-comment.yml (PR comment /demos full).
| Command | When | What it does |
|---|---|---|
bun run release:setup |
once per project | Idempotent wizard: workflows, Dependabot, script contract, first publish, first tag, trusted publisher, branch ruleset, auto-merge, then doctor. --dry-run prints every action, changes nothing and asks nothing. --yes answers every confirmation for an agent or CI; a step that needs your npm OTP is then printed, not run. |
bun run release:doctor |
any time | Changes nothing in the project; it only runs git fetch --tags first. Twelve checks, one line each, and the exact fix: command for every red line. --json for machines. |
bun run release wait |
after each merge to main |
Refuses unless origin/main holds HEAD. Waits for the first release tag that holds the commit, then for npm to serve that version. Stops on a failed run and prints the log command. |
bun run release fleet |
any time | Read-only. One table for every repository of the organization: CI on main, the release of main, tag against npm, commits nobody released, open PRs, old @moku-labs/* pins. Then the list of what waits for a person. --markdown prints the public rows for the organization page, --json every row. --deps adds two tables: the shared toolchain with the version most repositories are on, and the runtime dependencies that are behind npm. Only the dependencies a manifest names are read. |
bun run release <patch|minor|major|prerelease> |
a release a person asks for | Refuses unless the tree is clean and HEAD == origin/main. Dispatches publish.yml, watches the run, verifies the version and dist-tag on npm. |
The scripts are plain aliases of the moku-release bin. Internals and the list of checks:
src/README.md.
A package exposes these eight scripts. setup adds the ones that are missing;
doctor reports them.
| Script | Used by |
|---|---|
build |
build job, and again before npm pack |
validate |
build job — publint + attw |
lint |
lint job — biome check + eslint |
typecheck |
types job — tsc --noEmit |
test |
test job — vitest run, never bun test |
release:setup |
you — moku-release setup |
release:doctor |
you — moku-release doctor |
release |
you — moku-release |
Project-specific work goes inside the script. room needs a second typecheck pass, so its
script is "typecheck": "tsc --noEmit && tsc -p tsconfig.worker.json --noEmit". The central
YAML stays the same for everyone.
Important
Keep the caller's job id ci and the filename publish.yml. GitHub prefixes the check
names with the job id (ci / lint), and npm Trusted Publishing is registered against the
filename. Rename either and the ruleset or the publish breaks.
| Ref | Meaning |
|---|---|
@v1 |
Moving major tag. Projects pin this and get fixes automatically. Moves only for backwards-compatible changes. |
@v1.x.y |
Immutable tag on every change. Pin it to freeze a project. |
@v2 |
Any breaking change: a removed input, a changed default, a renamed job. v1 stays where it was. |
Important
v1 must be a lightweight tag. package-release.yml calls ./.github/workflows/package-ci.yml
from inside itself, and GitHub cannot resolve that relative call through an annotated tag: every
release dies with startup_failure and "workflow was not found". Immutable v1.x.y tags may be
annotated.
git tag -a v1.2.0 -m "v1.2.0"
git tag -f v1 v1.2.0^{commit} # no -a, no -m
git push origin v1.2.0 && git push -f origin v1A change here runs in every moku repo with contents: write and id-token: write. Review it
like release engineering, not like config.
The cross-repo OIDC publish was the open risk; npm accepted it on the first live release
(@moku-labs/ci@1.1.1). The fallback, should npm ever change that, and sixteen traps the
workflows already handle are in docs/release-notes.md.
bun run build # tsdown → dist/release.mjs
bun run validate # publint
bun run lint # biome check + eslint
bun run lint:fix
bun run format
bun run typecheck # tsc --noEmit
bun run test # vitest runNode ≥ 24 · Bun ≥ 1.3.14 · gh and npm ≥ 11.5.1 on the machine that runs setup or
release. The CLI prints through the
@moku-labs/common brand kit, bundled at build time.