Releasing
Luna is delivered from its public git repository, github.com/SATUNIX/luna. pi
installs it straight from there, so a pushed vX.Y.Z tag is the release: there is no package
registry in between.
| Channel | What it is | How users get it |
|---|---|---|
next |
Every commit on main |
Merging to main is enough |
latest |
The newest vX.Y.Z tag (the newest stable one once a stable release exists; betas until then) |
Push a tag |
X.Y.Z |
One tag, pinned | Push a tag |
The delivery is one setting, delivery in packages/core/distribution.json (git). The
installer, /profile and /update read it.
Releasing is manual and operator-run. Nothing in this repository tags, publishes or creates a release on its own, and the release workflow defaults to a dry run.
Cutting a release
main is protected, so a release lands through a reviewed pull request on GitHub, never a direct
push:
# 1. Fetch the tags, then branch from main with a clean tree. Add a "## [0.2.4-beta.4]" section
# to CHANGELOG.md and commit it.
git fetch --tags origin
git switch -c release/v0.2.4-beta.4 origin/main
# 2. Run the full gate, bump every package.json and the lockfile, commit, tag (local only).
# The gate is `npm ci --dry-run`, `npm run check:all` (about eight minutes), the lockfile check and a
# strict MkDocs build (`python -m pip install -r requirements-docs.txt` first; the script says so
# before it starts if MkDocs is missing):
npm run release -- 0.2.4-beta.4
# 3. Push the branch and merge it into main through a reviewed pull request:
git push -u origin release/v0.2.4-beta.4
# 4. Once the release commit is on main, push the tag:
git push origin v0.2.4-beta.4
release.ts never pushes. It refuses to run:
- on a dirty tree, or without a CHANGELOG section;
- when the version is already tagged, or is not newer than the newest release tag in the clone
(prerelease-aware:
0.2.4-beta.9 < 0.2.4-beta.10 < 0.2.4), which is why step 1 fetches the tags; - when the version is older than
package.json's.
npm run release -- 0.2.4-beta.4 --dry-run runs every gate without changing anything.
--bump-only syncs these without gates, commit or tag:
- the version fields;
- the README's version badge;
- the install pins in the README,
AGENTS.mdanddocs/; - the lockfile.
That prepares a release branch whose version change is reviewed on its own. After that branch
merges, npm run release -- <version> on main finds every version field already at the version,
so it only gates and tags. The first release, the version already in package.json before any
tag exists, works the same way. tests/release-plan-smoke.ts covers each of these cases, and
tests/docs-smoke.ts fails when a pin or the badge disagrees with package.json.
After the release pull request merges
Tag the release in the same sitting as the merge. The tag is the release, and until it exists the
version on main points at nothing: the install pins in the README and the docs name a tag that
cannot be installed, and the website keeps naming the previous tag. Two releases (0.2.4-beta.10
and 0.2.4-beta.11) were merged this way and never tagged.
V=0.3.0-beta.1 # the version that just merged
git fetch --tags origin && git switch main && git pull --ff-only
npm run release -- "$V" # gates, then tags the merged commit (local only)
git push origin "v$V" # the release
gh workflow run pages.yml --ref main # redeploy the website so it names the new tag
gh workflow run release.yml --ref "v$V" # dry run; then again with -f dry-run=false
Then check that it landed:
git ls-remote --tags origin "v$V"prints the tag;- the website's install command names it (the pages build warns
Release tag missingwhile it does not); - the GitHub Release exists once the non-dry run finishes.
Users on latest see a new release the next time /update checks (at most a day later, or
straight away with /update). A tag is the release even if a later workflow fails: /update
reads tags. If a release turns out wrong, fix it forward: release a new version with the fix,
and say in its notes which release it replaces. Never move, delete or recreate a tag once it is
public. Pinned installs and /update would then see a different release under the same name,
which Support rules out.
The release workflow
.github/workflows/release.yml adds two optional steps on top of a tag. It runs only when an
operator starts it from the Actions tab (workflow_dispatch); it never runs on a push, a tag or a
pull request.
| Job | Runs | Permissions | Side effects |
|---|---|---|---|
gate |
always | contents: read |
none: the whole of ci.yml for the same commit |
security |
always | contents: read, security-events: write, actions: read |
none beyond SARIF uploads: the whole of security.yml for the same commit |
plan |
always | contents: read |
none: plans the version and dist-tag, checks the tarball, runs npm publish --dry-run, previews the release notes in the run summary |
github-release |
only with dry-run unticked, from a v* tag |
contents: write |
creates the GitHub Release with the CHANGELOG notes |
npm-publish |
only with dry-run unticked and publish-npm ticked, from a v* tag |
id-token: write, the npm environment |
publishes @satunix/pi-system to npm |
dry-run defaults to ticked. The two jobs with side effects are guarded by an explicit
inputs.dry-run == false comparison, so any other event type, or an empty input, also means "no
side effects". plan waits for both gate and security, so the release gate is every check
CI runs for the commit, the security scans included, and the coverage and coverage-merge jobs,
which gate a release even though they no longer gate a pull request (Test coverage). tests/release-workflow-smoke.ts checks
this structure and is run by check:all, and it fails against a workflow that publishes on a dry
run or plans without the security gate.
flowchart LR
start([Operator starts the workflow]) --> gate[gate: the full CI checks]
start --> sec[security: the security workflow]
gate --> plan[plan: read-only dry run]
sec --> plan
plan --> q{dry-run unticked<br/>and a v* tag?}
q -->|no| done([Nothing published or created])
q -->|yes| rel[github-release: creates the Release]
q -->|yes, and publish-npm ticked| npm[npm-publish: npm environment]
Recommended order for a release:
- Land the release commit on
mainthrough a reviewed pull request (above), and wait for CI. - Push the tag (above).
- Run the
releaseworkflow from the tag with the defaults (dry run) and read theplansummary: tarball contents,npm publish --dry-runoutput, release notes. - Run it again from the tag with dry-run unticked to create the GitHub Release. Leave
publish-npmunticked unless npm publication has been set up (below).
Repository settings (GitHub)
The settings a release depends on are declared in .github/expected-settings.json and described,
field by field, in CI security. They are operator actions:
the repository does not change its own settings, and whether GitHub enforces what the file
declares is a setting a test cannot see. The Operator checklist lists
them with every other operator-only step. In short:
mainneeds a pull request with one approving review, code-owner review for the paths in.github/CODEOWNERS, approval of the last push, and every required check; force pushes and deletion are blocked, and the owner bypasses only through a pull request. When a matrix job is renamed,ci-completestill stands for every gatingci.ymljob (all but the measure-onlycoverageandcoverage-mergejobs), so the ruleset need not change.- Only the owner creates, updates or deletes
v*tags. - Agents push and open pull requests as a non-admin bot identity or GitHub App with contents and pull-request write access only, never as the owner, and are not bypass actors. With one required approval, an agent cannot merge its own pull request.
Release rules
- Publish what was reviewed. A release is a tag on a commit that reached
mainthrough a reviewed pull request;release.tsrefuses a dirty tree, and the release workflow only acts on a tag whose commit is onmainand matchespackage.json(tests/release-plan-smoke.ts,tests/release-workflow-smoke.ts). When npm publication is enabled, the npm job runs in thenpmenvironment, whose required reviewer andv*tag policy are declared in.github/expected-settings.json. - The release gate is every check.
gateandsecurityrun the whole ofci.ymlandsecurity.ymlfor the tagged commit beforeplan. - Fix forward. A tag is never moved, deleted or recreated once public (above).
- Tags are not signed. Release tags are annotated but carry no signature, and
/updatedoes not verify one; the tag rules and the review onmainare the controls. Signing is planned (Future work). - No branch-namespace rule. Anyone with write access can create a branch of any name; nothing is released from a branch, and only tags are releases.
- The authoritative forge is GitHub (Repository topology).
What a release contains
The whole repository at the tag. pi runs npm install --omit=dev --legacy-peer-deps in its copy,
which fetches Luna's one runtime dependency from the npm registry (Supply chain, "What
installing Luna pulls in"). Companion packages (pi-lens,
pi-readseek) are separate pi packages from npm, registered by the installer at Luna's
reviewed pins in packages/core/sources.json.
npm run smoke:package (part of check:all) packs the repository exactly as npm publish
would, unpacks it and proves the copy works alone, and smoke:clean-install installs that copy
for every profile and starts the real pi with it.
npm publication (optional)
npm delivery is built and tested but not enabled, and the package is not published. Git delivery is the supported path. To enable npm as well, an operator needs to:
- Have an npm account with two-factor authentication and the
satunixorganisation (it owns the@satunixscope). - Add a GitHub environment named
npm. - Publish the first version by hand (
npm login, thennpm publish --access public), because npm only lets you attach a trusted publisher to a package that exists. - On npmjs.com, package settings, Trusted Publisher, GitHub Actions: organisation
SATUNIX, repositoryluna, workflowrelease.yml, environmentnpm. Then set publishing access to "Require two-factor authentication and disallow tokens". - Set
"delivery": "npm"inpackages/core/distribution.jsononly if npm should replace git as the default; git delivery keeps working without it.
The npm channels are dist-tags: latest for releases, beta for prereleases once a stable release
exists, and release-X.Y for maintenance releases (packages/core/publish-plan.ts).
Local checks
npm run check:all # everything CI runs, including the delivery, update and install tests
npm run security:lockfile # lockfile integrity
node packages/core/release-notes.ts 0.2.4-beta.0 # preview the notes for a release
Where releases come from
GitHub SATUNIX/luna is the only repository: the release branch, its pull request and the
operator's tag all live here, following release.ts (tests/release-plan-smoke.ts). The GitLab
mirror and private-lineage export pipeline are archived; releases no longer arrive as exported
draft pull requests. Earlier development happened in a private GitLab project, now archived
(Repository topology).
Releases that change scan exceptions
The leak-scan pull-request check reads packages/core/leak-scan-exceptions.json from main,
never from the pull request, and fails any pull request that changes that file together with
other files (tests/prepush-scan-smoke.ts; CI security). A release pull
request gets no exemption.
If a release needs a new exception:
- Open a pull request containing only the exceptions change. Review every entry against the content it admits, then merge that pull request first.
- Update the release branch from
main. Its changes must now exclude the exceptions file, andleak-scanmust pass with the exceptions read frommain. - Merge the release pull request after review and every required check, then let the operator tag the release as described above.
There is no export job or release bot preparing these pull requests. Contributors prepare them here under the same review and leak-scan rules as every other change.