Skip to content
moku-labsPublic

About

Reusable GitHub workflows pinned by tag, plus the moku-release CLI that installs them into a project and runs a release

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

@moku-labs/ci

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.


npm self test workflows node license: MIT


Install · How it works · Workflows · Project checks · PR previews · Demos · CLI · The contract · Versioning · Scripts


Install

bun add -d @moku-labs/ci
bun run release:setup

setup 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

Why @moku-labs/ci

  • One copy of the pipeline. Eight packages had eight different ci.yml and eight different publish.yml. A fix now lands here and reaches every project through the @v1 tag.
  • Scripts are the interface, not tools. The workflows call bun run lint, never biome. A project with special needs changes its own script, not the central YAML.
  • The CLI and its templates are one package. moku-release reads examples/ and rulesets/ 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/core can use it without a cycle.

How it works

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
Loading
  1. release:setup writes two thin callers into .github/workflows/.
  2. Every PR runs package-ci.yml: four jobs, reported as ci / lint, ci / types, ci / test, ci / build.
  3. Every merge to main runs publish.yml, which calls package-release.yml: check → tag → pack → publish. The version is always a patch. release wait waits for it and verifies the version on npm.
  4. A person runs release minor, or release major for a milestone. It dispatches the same publish.yml.
Who releases Version
a merge to main patch, always
a person minor
a person, for a milestone major

Workflows

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.

Project checks

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.

PR previews

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

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).

CLI

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.

The contract

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.

Versioning

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 v1

A change here runs in every moku repo with contents: write and id-token: write. Review it like release engineering, not like config.

When a release fails

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.

Scripts

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 run

Requirements

Node ≥ 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.

License

MIT © moku-labs

About

Reusable GitHub workflows pinned by tag, plus the moku-release CLI that installs them into a project and runs a release

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages