@sovereignfs/create 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sovereignfs/create",
3
- "version": "0.12.0",
3
+ "version": "0.14.0",
4
4
  "type": "module",
5
5
  "description": "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
6
6
  "license": "AGPL-3.0-or-later",
@@ -26,10 +26,10 @@
26
26
  "devDependencies": {
27
27
  "@sovereignfs/tsconfig": "0.0.0",
28
28
  "@types/node": "^24.19.2",
29
+ "@types/semver": "^7.8.0",
29
30
  "ajv": "^8.20.0",
30
31
  "ajv-formats": "^3.0.1",
31
- "semver": "^7.8.5",
32
- "@types/semver": "^7.7.1",
32
+ "semver": "^7.8.6",
33
33
  "tsup": "^9.0.0",
34
34
  "typescript": "~6.0.3"
35
35
  },
@@ -0,0 +1,49 @@
1
+ # AGENTS.md
2
+
3
+ Guidance for every AI agent working on **TITLE** (Claude Code reads it through `CLAUDE.md`). The sections above and below the shared one are
4
+ this app's own; the shared one is written by `npm create @sovereignfs app sync` and is the same in every app of the suite.
5
+
6
+ ## What this is
7
+
8
+ **TITLE** is an app for a [Sovereign](https://github.com/sovereignfs/sovereign) instance. Say here what it does and for whom.
9
+
10
+ ## Source of truth
11
+
12
+ - `README.md`: what is here, how to build, host and run it.
13
+ - `sovereign.manifest.json`: what an instance needs to know to host it.
14
+ - `CONTRIBUTING.md` and `RELEASING.md`: how work lands and how a version is released.
15
+
16
+ <!-- sovereign:shared:begin -->
17
+
18
+ ## Working conventions (shared by every app of the suite)
19
+
20
+ - **Two branches.** Work lands on `develop`, committed directly or through a feature branch (`feat/`, `fix/`, `docs/`, `chore/` and a
21
+ slug) cut from an up-to-date `develop` and merged into it by draft pull request with rebase and merge. `main` is what is released: it
22
+ is protected and changes only by a promotion pull request from `develop`, merged with a merge commit (`CONTRIBUTING.md`).
23
+ - **Never commit or push without being asked.** Prepare changes in the working tree and stop. **Never merge a pull request
24
+ automatically.**
25
+ - **Commits explain why, not just what:** `type(scope): summary` (`feat`, `fix`, `docs`, `chore`) under 72 characters, a body wrapped at
26
+ 100, a `Verified:` line naming what was run, one logical change each. An agent's commits end with its own model-agnostic trailer:
27
+ `Co-Authored-By: Claude Code <noreply@anthropic.com>` or `Co-Authored-By: Codex <noreply@openai.com>`, never one naming a model (the
28
+ promotion check refuses it).
29
+ - **Pull requests into `develop` are drafts,** marked ready only on instruction; the body says what changed and why and ends with the
30
+ agent's footer.
31
+ - **A version is set with its changelog section,** in the same change: `version` in `package.json` (or, in a repository of several
32
+ components, the file `sovereign.json` names for it) and `## [X.Y.Z] - date` in its changelog, in plain words for someone upgrading. A
33
+ promotion titled `Release` with that version's tag publishes it on merge (`RELEASING.md`).
34
+ - **CI runs only for `main`:** on pull requests into it that are not drafts, before a release and by hand; never for `develop` or a
35
+ feature branch, which the pre-push hook (`npm run verify`) checks locally.
36
+ - **Verify before claiming done,** and show the output. A regression test is trusted only after it has been seen to fail against the code
37
+ it guards.
38
+ - **Docs are part of the change:** a statement a change makes false is fixed in the same change.
39
+ - **Flag Docker-config impact immediately:** a new or renamed environment variable, port, on-disk path or native dependency updates the
40
+ `Dockerfile`, `.dockerignore` and Compose files in the same change.
41
+ - **Shared files are written, not edited:** the files `npm create @sovereignfs app sync` writes (this section among them) are changed
42
+ in the template, in sovereignfs/sovereign, and taken with the next sync; a file this app keeps as its own is listed in `package.json`
43
+ under `sovereign.unmanaged`.
44
+
45
+ <!-- sovereign:shared:end -->
46
+
47
+ ## Rules of this app
48
+
49
+ Say here what is particular to this app: its data, its pages, what it must never do.
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ What changed in each version of **TITLE**, newest first, in the form of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
4
+ versions follow [semver](https://semver.org/). A version's section is written in the change that sets the version, dated that day, and
5
+ becomes its GitHub release's notes (RELEASING.md).
6
+
7
+ ## [0.1.0] - 2026-01-01
8
+
9
+ ### Added
10
+
11
+ - The app, as `npm create @sovereignfs app` made it.
@@ -0,0 +1,9 @@
1
+ # CLAUDE.md
2
+
3
+ Written by `npm create @sovereignfs app sync`; do not edit it here. The conventions for this repository live in [AGENTS.md](AGENTS.md),
4
+ shared by every agent; Claude Code loads it through the import below.
5
+
6
+ @AGENTS.md
7
+
8
+ Claude Code's commit trailer is `Co-Authored-By: Claude Code <noreply@anthropic.com>`: model-agnostic, even if your harness suggests a
9
+ model-specific one.
@@ -2,7 +2,10 @@
2
2
 
3
3
  How work gets into `develop`, and from there into `main`. It is the workflow of
4
4
  [Sovereign](https://github.com/sovereignfs/sovereign/blob/main/CONTRIBUTING.md) itself, so an app made with
5
- `npm create @sovereignfs app` is worked on the same way.
5
+ `npm create @sovereignfs app` is worked on the same way. The sections above and below the shared one are this app's own (how to set it
6
+ up, how it is planned); the shared one is written by `npm create @sovereignfs app sync` and is the same in every app of the suite.
7
+
8
+ <!-- sovereign:shared:begin -->
6
9
 
7
10
  ## Branches
8
11
 
@@ -37,50 +40,61 @@ commit; fix commit messages before they reach `develop`, which is never rewritte
37
40
 
38
41
  ## Continuous integration
39
42
 
40
- CI (`.github/workflows/ci.yml`: typecheck, the manifest check, the build) runs only where a change is about to reach what is
41
- released:
43
+ CI runs only where a change is about to reach what is released:
42
44
 
43
45
  - on a pull request into `main` that is not a draft (the promotion from `develop`); marking a draft ready for review runs it;
44
- - on each release tag, before the image is built (`.github/workflows/publish.yml` calls it);
46
+ - before each release is published (the publish workflow runs the checks on the tagged commit);
45
47
  - by hand, for any branch: **Actions → CI → Run workflow**.
46
48
 
47
49
  It never runs on a push to `develop` or a feature branch, nor on a pull request into `develop`, so runner time is not spent on every
48
- commit. Those are checked on your machine instead: `npm install` turns on the versioned hooks in `.githooks/`, and the pre-push hook runs
49
- `npm run verify` (typecheck and the manifest check) before anything is pushed. This is the CI strategy of every Sovereign app.
50
+ commit. Those are checked on your machine instead: where the repository has versioned hooks in `.githooks/` (an app's `npm install` turns
51
+ them on), the pre-push hook runs its checks (`npm run verify`) before anything is pushed. This is the CI strategy of every repository of
52
+ the suite.
50
53
 
51
54
  ## Promoting `develop` into `main`
52
55
 
53
- 1. Set the new version in `package.json` on `develop` (semver: a fix is a patch, a feature a minor, a break a major).
54
- 2. Open a pull request from `develop` into `main`. Its title is the version, **`vX.Y.Z`**, or **`Release vX.Y.Z`** when that version
55
- will be tagged and published once it is merged; not every version is. The body lists what it carries.
56
- 3. Merge it with **a merge commit**, the one place a merge commit is used; the merge commit takes the pull request's title.
57
- `develop` is never rewritten, so it stays an ancestor of `main` and the next pull request shows only what is new.
58
- 4. To publish, tag the merge commit and push the tag, which builds and publishes the image (`.github/workflows/publish.yml`):
59
-
60
- ```bash
61
- git switch main && git pull
62
- git tag vX.Y.Z && git push origin vX.Y.Z
63
- ```
56
+ `main` changes only through a promotion pull request from `develop`, merged with **a merge commit**, the one place a merge commit is
57
+ used; `develop` is never rewritten, so it stays an ancestor of `main` and the next promotion shows only what is new. Its title is the
58
+ version, **`vX.Y.Z`**, or **`Release vX.Y.Z`** when merging it is to publish that version, which [RELEASING.md](RELEASING.md) describes:
59
+ there is no release script, and no tag to push by hand.
64
60
 
65
- A tag is not a branch, so `main`'s protection does not stop it; the workflow refuses a tag whose commit is not on `main`, or whose
66
- version is not the one in `package.json`.
61
+ The **Promotion** check, which `main` requires, holds the title to the code, refuses a commit whose agent trailer names a model, and
62
+ fails when a shared file differs from the template (below). Editing the title runs it again.
67
63
 
68
64
  Once the promotion is merged, `.github/workflows/sync-develop.yml` moves `develop` forward to the merge commit. It is a fast-forward,
69
65
  never a rewrite (`develop` is already in the merge commit's history), so `develop` is not shown as behind `main` and the release tags are
70
66
  in its history. If a commit reached `develop` after the merge, the run leaves `develop` as it is and says so; pull before you start new
71
67
  work either way.
72
68
 
73
- ## Setting it up on GitHub
69
+ ## Shared files
74
70
 
75
- Once the repository is on GitHub, push both branches and protect `main`:
71
+ Some files are the same in every app of the suite and are written, not edited: `.github/workflows/promotion.yml`, `release.yml` and
72
+ `sync-develop.yml`, `.github/repository.json`, `CLAUDE.md`, and the shared sections of this file, `RELEASING.md` and `AGENTS.md`. They come
73
+ from the template of the version of `@sovereignfs/create` that `package.json` pins:
74
+
75
+ ```bash
76
+ npm create @sovereignfs app sync # write them from the pinned version's template
77
+ npm create @sovereignfs app sync --check # say which differ, and fail; the Promotion check runs this
78
+ ```
79
+
80
+ To change one, change it in the template, in [sovereignfs/sovereign](https://github.com/sovereignfs/sovereign), and take it here by moving
81
+ the pin and running `sync`. A file this app keeps as its own is listed in `package.json` under `sovereign.unmanaged`, by its path from the
82
+ repository's root, and the check then leaves it alone.
83
+
84
+ ## Repository settings
85
+
86
+ The repository's merge settings and its rulesets (what `main` and `develop` allow, and the checks `main` requires) are code, in
87
+ `.github/repository.json`, and are never set in GitHub's interface. Once the repository is on GitHub, push both branches and apply them,
88
+ signed in with `gh` as an owner of the repository:
76
89
 
77
90
  ```bash
78
91
  git push -u origin main develop
92
+ npm create @sovereignfs app settings apply # make GitHub match .github/repository.json
93
+ npm create @sovereignfs app settings check # say what differs, and fail
79
94
  ```
80
95
 
81
- Then, in **Settings → Rules → Rulesets**, add a ruleset for the default branch `main` that requires a pull request before merging, allows
82
- merge commits, and blocks force pushes and deletion, with the Repository admin role allowed to bypass it. Add a second ruleset for `develop`
83
- that blocks deletion and force pushes, with no one allowed to bypass it: GitHub's "Automatically delete head branches" setting would
84
- otherwise delete `develop` when a promotion is merged, and it leaves a branch alone when its deletion is blocked. In **Settings → General → Pull
85
- Requests**, keep merge commits and rebase merging allowed, and set the default merge commit message to the pull request's title and
86
- description, so the merge commit reads `vX.Y.Z` or `Release vX.Y.Z`.
96
+ `main` takes changes only by pull request, merged with a merge commit, and requires the Promotion check and the checks under
97
+ `sovereign.requiredChecks` in `package.json` (`requiredChecks` in `sovereign.json` for a repository of several components); `develop` can never be deleted or force-pushed, so merging a promotion (which would
98
+ otherwise delete its head branch) leaves it in place. A change to the settings is a commit like any other, applied after it lands.
99
+
100
+ <!-- sovereign:shared:end -->
@@ -12,6 +12,10 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
12
12
  | `Dockerfile` | One image, not root, on the manifest's port. Its label and port are made from the manifest when it is built |
13
13
  | `.github/workflows/publish.yml` | On a `vX.Y.Z` tag of a commit on `main`, builds the image for amd64 and arm64 and publishes it to `ghcr.io/<owner>/<repository>` |
14
14
  | `CONTRIBUTING.md` | How work lands on `develop` and is released to `main` (below) |
15
+ | `RELEASING.md`, `CHANGELOG.md` | How a version is released (a promotion titled `Release vX.Y.Z`), and each version's notes |
16
+ | `AGENTS.md`, `CLAUDE.md` | The conventions for agents: the app's own sections, and one shared by every app of the suite |
17
+ | `.github/repository.json` | The repository's merge settings and rulesets, as code (`npm create @sovereignfs app settings apply`) |
18
+ | `.github/workflows/promotion.yml`, `release.yml` | The promotion check and the release on merge, which call the workflows every app shares |
15
19
  | `.github/workflows/ci.yml`, `.githooks/pre-push` | The checks: CI for pull requests into `main` and release tags only, the pre-push hook for everything else |
16
20
  | `.github/workflows/sync-develop.yml` | After a promotion into `main` is merged, fast-forwards `develop` to the merge commit |
17
21
  | `app/auth/[action]/route.ts` | Sign-in, sign-out, core's back-channel logout, and core's notice that a person deleted their account |
@@ -26,7 +30,7 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
26
30
 
27
31
  Work lands on `develop`, committed directly or merged from a feature branch; `main` is what is released, protected, and changed only by a
28
32
  pull request from `develop` titled with its version, merged with a merge commit, which is tagged `vX.Y.Z` when that version is published. `npm create @sovereignfs app`
29
- made both branches and left you on `develop`. [CONTRIBUTING.md](CONTRIBUTING.md) has the whole workflow, and how to protect `main` on
33
+ made both branches and left you on `develop`. [CONTRIBUTING.md](CONTRIBUTING.md) has the whole workflow, the shared files `npm create @sovereignfs app sync` keeps, and how `main` is protected on
30
34
  GitHub.
31
35
 
32
36
  ## Build and host it
@@ -0,0 +1,31 @@
1
+ # Releasing **TITLE**
2
+
3
+ The sections above and below the shared one are this repository's own (what is particular to how it publishes); the shared one is
4
+ written by `npm create @sovereignfs app sync` and is the same in every repository of the suite.
5
+
6
+ <!-- sovereign:shared:begin -->
7
+
8
+ A release is a promotion of `develop` into `main` that says it is one. There is no release script to run.
9
+
10
+ 1. **Set the version and its changelog section on `develop`,** in the change that makes them: `version` in `package.json` (semver: a
11
+ fix is a patch, a feature a minor, a break a major) and a section `## [X.Y.Z] - YYYY-MM-DD` in `CHANGELOG.md`, saying in plain words
12
+ what changed for someone upgrading. The section is the release's notes; a promotion titled `Release` is refused without it.
13
+ 2. **Open the promotion pull request** from `develop` into `main`, titled **`vX.Y.Z`**, or **`Release vX.Y.Z`** when merging it is to
14
+ publish that version. The **Promotion** check holds the title to the code: the version must be the one in `package.json`, and a
15
+ `Release` title must name a version not tagged yet, with its changelog section. Editing the title runs it again.
16
+ 3. **Merge it with a merge commit** (the only method `main` allows). For a `Release` title, the **Release** workflow checks the title
17
+ against the merged code, tags the merge commit `vX.Y.Z`, and calls `.github/workflows/publish.yml`, which runs the app's checks,
18
+ publishes the image to `ghcr.io/<owner>/<repository>:X.Y.Z` and makes the GitHub release from the changelog section.
19
+
20
+ A version promoted without `Release` can be published later by pushing its tag on the merge commit that brought it:
21
+
22
+ ```bash
23
+ git switch main && git pull
24
+ git tag vX.Y.Z <merge commit> && git push origin vX.Y.Z
25
+ ```
26
+
27
+ The promotion check and the release are workflows every app of the suite shares, kept in
28
+ [sovereignfs/sovereign](https://github.com/sovereignfs/sovereign/tree/main/.github/workflows) and run with the version of
29
+ `@sovereignfs/create` this app pins in `package.json`.
30
+
31
+ <!-- sovereign:shared:end -->
@@ -0,0 +1,50 @@
1
+ {
2
+ "settings": {
3
+ "default_branch": "main",
4
+ "allow_merge_commit": true,
5
+ "allow_rebase_merge": true,
6
+ "allow_squash_merge": false,
7
+ "merge_commit_title": "PR_TITLE",
8
+ "merge_commit_message": "PR_BODY",
9
+ "delete_branch_on_merge": true
10
+ },
11
+ "rulesets": [
12
+ {
13
+ "name": "main is released through promotion pull requests",
14
+ "target": "branch",
15
+ "enforcement": "active",
16
+ "conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
17
+ "bypass_actors": [{ "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }],
18
+ "rules": [
19
+ { "type": "deletion" },
20
+ { "type": "non_fast_forward" },
21
+ {
22
+ "type": "pull_request",
23
+ "parameters": {
24
+ "required_approving_review_count": 0,
25
+ "dismiss_stale_reviews_on_push": false,
26
+ "require_code_owner_review": false,
27
+ "require_last_push_approval": false,
28
+ "required_review_thread_resolution": false,
29
+ "allowed_merge_methods": ["merge"]
30
+ }
31
+ },
32
+ {
33
+ "type": "required_status_checks",
34
+ "parameters": {
35
+ "strict_required_status_checks_policy": false,
36
+ "required_status_checks": [{ "context": "Promotion / Promotion title" }]
37
+ }
38
+ }
39
+ ]
40
+ },
41
+ {
42
+ "name": "develop is never deleted or rewritten",
43
+ "target": "branch",
44
+ "enforcement": "active",
45
+ "conditions": { "ref_name": { "include": ["refs/heads/develop"], "exclude": [] } },
46
+ "bypass_actors": [],
47
+ "rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
48
+ }
49
+ ]
50
+ }
@@ -11,10 +11,16 @@ on:
11
11
  types: [opened, synchronize, reopened, ready_for_review]
12
12
  workflow_dispatch:
13
13
  workflow_call:
14
+ inputs:
15
+ ref:
16
+ description: The tag to check, when publish.yml is called for a release; empty for what triggered the run.
17
+ type: string
18
+ required: false
19
+ default: ''
14
20
 
15
21
  concurrency:
16
- group: ci-${{ github.event.pull_request.number || github.sha }}
17
- cancel-in-progress: ${{ github.event_name == 'pull_request' }}
22
+ group: ci-${{ inputs.ref || github.event.pull_request.number || github.sha }}
23
+ cancel-in-progress: ${{ github.event_name == 'pull_request' && inputs.ref == '' }}
18
24
 
19
25
  permissions:
20
26
  contents: read
@@ -25,11 +31,13 @@ jobs:
25
31
  runs-on: ubuntu-latest
26
32
  timeout-minutes: 20
27
33
  # A draft pull request runs nothing; marking it ready for review runs it.
28
- if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
34
+ # A release run (`ref` given) always runs.
35
+ if: inputs.ref != '' || github.event_name != 'pull_request' || github.event.pull_request.draft == false
29
36
  steps:
30
37
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
31
38
  with:
32
39
  persist-credentials: false
40
+ ref: ${{ inputs.ref }}
33
41
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
34
42
  with:
35
43
  node-version: 24
@@ -0,0 +1,24 @@
1
+ name: Promotion
2
+
3
+ # Written by `npm create @sovereignfs sync`; do not edit it here (CONTRIBUTING.md, "Shared files"). Checks a promotion pull request
4
+ # (develop -> main) with the workflow every app of the suite shares: its title names this app's version, its commits carry only the agent
5
+ # trailers allowed, and the shared files are the template's. `main` requires this check (.github/repository.json).
6
+ on:
7
+ pull_request:
8
+ branches: [main]
9
+ types: [opened, edited, synchronize, reopened, ready_for_review]
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ concurrency:
15
+ group: promotion-${{ github.event.pull_request.number }}
16
+ cancel-in-progress: true
17
+
18
+ jobs:
19
+ promotion:
20
+ name: Promotion
21
+ uses: sovereignfs/sovereign/.github/workflows/app-promotion.yml@__WORKFLOWS_REF__
22
+ with:
23
+ directory: '__DIRECTORY__'
24
+ tag-prefix: '__TAG_PREFIX__'
@@ -1,11 +1,14 @@
1
1
  name: Publish
2
2
 
3
- # Builds this app's image when a version tag is pushed, and publishes it to GitHub's container registry as ghcr.io/<owner>/<repository>
4
- # tagged X.Y.Z, which is where `sv app add --git` looks for it (operator-cli §4.2.1):
3
+ # Builds this app's image and publishes it to GitHub's container registry as ghcr.io/<owner>/<repository> tagged X.Y.Z, which is where
4
+ # `sv app add --git` looks for it (operator-cli §4.2.1), then makes the version's GitHub release from its CHANGELOG.md section. The
5
+ # release workflow (release.yml) calls it with the tag when a promotion titled `Release vX.Y.Z` is merged (RELEASING.md); a tag pushed by
6
+ # hand starts it too:
5
7
  #
6
8
  # git tag v1.0.0 && git push origin v1.0.0
7
9
  #
8
- # Nothing is published unless the checks in ci.yml pass on the tagged commit and that commit is on `main`.
10
+ # Nothing is published unless the checks in ci.yml pass on the tagged commit, that commit is on `main`, and the version has a changelog
11
+ # section.
9
12
  #
10
13
  # The image carries the manifest as its label and is built to listen on the manifest's port, both made from sovereign.manifest.json by
11
14
  # @sovereignfs/manifest, so the manifest is written once.
@@ -13,31 +16,44 @@ on:
13
16
  push:
14
17
  tags:
15
18
  - 'v*.*.*'
19
+ workflow_call:
20
+ inputs:
21
+ tag:
22
+ description: The tag to publish, such as v1.2.0; it exists already, on the promotion's merge commit.
23
+ type: string
24
+ required: true
16
25
 
17
26
  permissions:
18
27
  contents: read
19
- packages: write
20
28
 
21
29
  jobs:
22
30
  # The app's checks (ci.yml) on the tagged commit, before anything is built or published.
23
31
  validate:
24
32
  uses: ./.github/workflows/ci.yml
33
+ with:
34
+ ref: ${{ inputs.tag }}
25
35
 
26
36
  image:
27
37
  needs: validate
28
38
  runs-on: ubuntu-latest
39
+ permissions:
40
+ contents: read
41
+ packages: write
42
+ outputs:
43
+ version: ${{ steps.version.outputs.version }}
29
44
  steps:
30
45
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
31
46
  with:
32
47
  persist-credentials: false
33
48
  fetch-depth: 0
49
+ ref: ${{ inputs.tag }}
34
50
 
35
51
  # A release is the merge commit of a pull request from `develop` into `main` (CONTRIBUTING.md), never a commit of `develop` or of a
36
52
  # branch that was tagged by mistake.
37
53
  - name: Check the tagged commit is on main
38
54
  run: |
39
55
  git fetch --no-tags origin main
40
- if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
56
+ if ! git merge-base --is-ancestor HEAD origin/main; then
41
57
  echo "The tagged commit is not on main; refusing to publish." >&2
42
58
  exit 1
43
59
  fi
@@ -49,15 +65,22 @@ jobs:
49
65
 
50
66
  # The tag names the version, so it has to be the one the package says. The image is tagged X.Y.Z, without the v.
51
67
  - id: version
68
+ env:
69
+ TAG: ${{ inputs.tag || github.ref_name }}
52
70
  run: |
53
- expected="${GITHUB_REF_NAME#v}"
71
+ expected="${TAG#v}"
54
72
  actual="$(node -p "require('./package.json').version")"
55
73
  if [ "$actual" != "$expected" ]; then
56
- echo "The tag $GITHUB_REF_NAME expects version $expected, but package.json says $actual." >&2
74
+ echo "The tag $TAG expects version $expected, but package.json says $actual." >&2
57
75
  exit 1
58
76
  fi
59
77
  echo "version=$expected" >> "$GITHUB_OUTPUT"
60
78
 
79
+ # The release notes are the version's CHANGELOG.md section (RELEASING.md); a version without one is not published.
80
+ - run: npx create app release notes "$TAG" > /dev/null
81
+ env:
82
+ TAG: ${{ inputs.tag || github.ref_name }}
83
+
61
84
  # Fails the build on a manifest an instance would refuse.
62
85
  - run: npx sovereign-manifest check
63
86
 
@@ -82,3 +105,29 @@ jobs:
82
105
  tags: ${{ steps.image.outputs.name }}:${{ steps.version.outputs.version }}
83
106
  labels: ${{ steps.manifest.outputs.labels }}
84
107
  build-args: ${{ steps.manifest.outputs.build-args }}
108
+
109
+ # The GitHub release for the tag, with the version's CHANGELOG.md section as its notes. Run again, it replaces the notes.
110
+ release:
111
+ needs: image
112
+ runs-on: ubuntu-latest
113
+ permissions:
114
+ contents: write
115
+ steps:
116
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
117
+ with:
118
+ persist-credentials: false
119
+ ref: ${{ inputs.tag }}
120
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
121
+ with:
122
+ node-version: 24
123
+ - run: npm ci --ignore-scripts --no-audit --no-fund
124
+ - env:
125
+ GH_TOKEN: ${{ github.token }}
126
+ TAG: ${{ inputs.tag || github.ref_name }}
127
+ run: |
128
+ npx create app release notes "$TAG" > notes.md
129
+ if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
130
+ gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --notes-file notes.md
131
+ else
132
+ gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --notes-file notes.md
133
+ fi
@@ -0,0 +1,40 @@
1
+ name: Release
2
+
3
+ # Written by `npm create @sovereignfs sync`; do not edit it here (CONTRIBUTING.md, "Shared files"). When a promotion pull request titled
4
+ # `Release vX.Y.Z` is merged, the workflow every app of the suite shares checks the title against the merged code and tags the merge
5
+ # commit; this app's own publish workflow then builds and publishes that tag (RELEASING.md). A title without `Release` publishes nothing.
6
+ on:
7
+ pull_request:
8
+ branches: [main]
9
+ types: [closed]
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ concurrency:
15
+ group: release-${{ github.event.pull_request.number }}
16
+ cancel-in-progress: false
17
+
18
+ jobs:
19
+ plan:
20
+ name: Plan
21
+ permissions:
22
+ contents: write
23
+ uses: sovereignfs/sovereign/.github/workflows/app-release.yml@__WORKFLOWS_REF__
24
+ with:
25
+ directory: '__DIRECTORY__'
26
+ tag-prefix: '__TAG_PREFIX__'
27
+
28
+ publish:
29
+ name: Publish
30
+ needs: plan
31
+ if: needs.plan.outputs.tag != ''
32
+ permissions:
33
+ contents: write
34
+ packages: write
35
+ id-token: write
36
+ attestations: write
37
+ uses: ./.github/workflows/publish.yml
38
+ with:
39
+ tag: ${{ needs.plan.outputs.tag }}
40
+ secrets: inherit
@@ -0,0 +1,27 @@
1
+ # Releasing **TITLE**
2
+
3
+ The sections above and below the shared one are this repository's own (what is particular to how it publishes); the shared one is
4
+ written by `npm create @sovereignfs app sync` and is the same in every repository of the suite.
5
+
6
+ <!-- sovereign:shared:begin -->
7
+
8
+ This repository releases several components, each with its own version, tag and changelog, listed in `sovereign.json`. A release is a
9
+ promotion of `develop` into `main` that says which of them it publishes. There is no release script.
10
+
11
+ 1. **Set each component's version and its changelog section on `develop`,** in the change that makes them: the version in the file
12
+ `sovereign.json` names for it (semver: a fix is a patch, a feature a minor, a break a major), and a section `## [X.Y.Z] - YYYY-MM-DD`
13
+ in its changelog, saying in plain words what changed for someone upgrading. The section is the release's notes.
14
+ 2. **Open the promotion pull request** from `develop` into `main`, titled with the versions it carries, by their tags (each component's tag
15
+ prefix, then `vX.Y.Z`, such as `web-v1.2.0`), and starting with **`Release`** when merging it is to publish them:
16
+ `Release web-v1.2.0, cli-v0.6.0`. The **Promotion** check holds the title to the code: each version must be its component's current
17
+ one, and under `Release` not tagged yet, with its changelog section. Editing the title runs it again.
18
+ 3. **Merge it with a merge commit** (the only method `main` allows). For a `Release` title, the **Release** workflow checks the title
19
+ against the merged code, tags the merge commit with each version, and calls each component's publish workflow with its tag.
20
+
21
+ A version promoted without `Release` can be published later by pushing its tag on the merge commit that brought it.
22
+
23
+ The promotion check and the release are workflows every repository of the suite shares, kept in
24
+ [sovereignfs/sovereign](https://github.com/sovereignfs/sovereign/tree/main/.github/workflows) and run with the version of
25
+ `@sovereignfs/create` that `sovereign.json` pins.
26
+
27
+ <!-- sovereign:shared:end -->