Releasing create-kb

This page is for maintainers of this repository. Site authors who only write docs can ignore it.

A release is a git tag on main that looks like v1.2.0. GitHub Actions assembles the starter, publishes create-kb to npm, and opens a GitHub Release.

One-time npm setup

You do not need an npm org. Packages is empty until create-kb exists. Trusted Publisher lives on the package page, so the first version is published from your laptop with 2FA. After that, tags use GitHub Actions with no token.

Cancel the Bypass 2FA token form. You do not need it.

1. Create the package (once, on your machine)

From this repo, on main, with Node 20+:

npm login and npm publish will ask for your npm 2FA code. That is correct.

When it succeeds, npmjs.com/package/create-kb exists under your account. Packages will show 1 package.

2. Attach Trusted Publishing (for every later tag)

Open create-kb → Access / Trusted Publisher (package settings, not the empty account Packages list).

GitHub Actions, then fill exactly:

| Field | Value | |---|---| | Organization or user | Your GitHub user that owns this repo (example: adamBoualleiguie) | | Repository | knowledge-base | | Workflow filename | publish-create-kb.yml | | Environment name | leave empty | | Allowed actions | npm publish |

Filename only, not .github/workflows/.... Save.

No GitHub NPM_TOKEN secret. Later git push origin v1.2.0 publishes from CI.

Every release

1. Land the feature on main as usual (the GitHub Pages workflow still deploys this site).
2. Update packages/create-kb/CHANGELOG.md:
   • Move notes from Unreleased into a ## 1.2.0 - YYYY-MM-DD section.
   • For a major, add a short "Migration" subsection (what 1.x owners must change if they opt in).
3. Match the version in packages/create-kb/package.json to the tag you will push (optional but keeps local yarn create-kb stamps honest). The Action always sets the published version from the tag.
4. On main:

5. Watch Actions → Publish create-kb. It will:
   • Reject the tag if that commit is not on origin/main
   • Reject tags that are not exactly vMAJOR.MINOR.PATCH (no -beta)
   • Assemble packages/create-kb/template
   • npm publish from packages/create-kb
   • Create a GitHub Release with the changelog excerpt

People then run:

Version choice

| You shipped | Tag | Who is affected | |---|---|---| | Bugfix in Author Studio or starter | v1.2.1 | New scaffolds. Existing 1.2.0 repos stay as they are | | New optional MDX feature or config key | v1.3.0 | New scaffolds get it. 1.2 sites keep building | | Breaking rename, required config, dropped Node | v2.0.0 | New scaffolds only, plus a migration section in the changelog |

Existing 1.2 sites do not auto-upgrade. That is intentional. See Versions and upgrades.

Local dry run (no npm)

Inspect ./tmp/release-smoke/kb.engine.json. Revert the version bump if you were only testing.

Do not use --no-verify on the publish workflow. Do not publish from a branch that is not main.

If publish fails

• 403 / ENEEDAUTH on npm: Trusted Publisher fields do not match (GitHub user, repo knowledge-base, workflow file publish-create-kb.yml). Fix on npmjs.com and re-run the failed job, or push the tag again.
• Tag not on main: merge first, delete the bad tag if needed, retag the merge commit.
• Invalid tag: only v1.2.3. Not create-kb-v1.2.3, not v1.2.3-rc.1 (prerelease tags are not wired yet).

See also

• Create a knowledge base (CLI)
• Versions and upgrades