Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 46 additions & 4 deletions docs/release-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,11 @@ Three terms:
- **One run owns one release.** Build, tag, release and publish are
jobs of one workflow run, linked with `needs`.
- Why: a failure in one job stops the next, and the run is red.
- The trigger covers every branch that can release. An rc PR or a
maintenance release can target another branch than `main`. A
`branches` filter on the trigger then starts no run for it: the
branch has the version, but no tag and no publish. Let the
condition on the first job decide which PRs release.
- Check: can you reach every job of the release from one run page?

- **Call, do not chain by event.** A shared build is a reusable
Expand Down Expand Up @@ -106,6 +111,13 @@ Three terms:
- Why: their failure makes the run red, but the release jobs stay
green, so it is clear that the release is complete.
- Do not use `continue-on-error` for them: it hides the failure.
- A step that writes to one shared place, such as a docs site with
one version, checks three facts first: this run released the
package that the place belongs to, the version is not a
pre-release, and the run is for the main line. Read these from the
fields of the handoff, such as `package` and `prerelease` in
`releases`. Do not search the handoff for a substring: after an
rc, `previous_version` of the stable release contains `-rc.`.
- A publish to a second registry is not such a step. It is part of
the release.

Expand Down Expand Up @@ -133,10 +145,19 @@ Three terms:
evaluated when the run starts and can use only `github`, `inputs`
and `vars`.
- Never use a constant group, or a group per branch, on a workflow
that also starts for other events. A group holds one running and
one waiting run. A third run cancels the waiting one, also with
`cancel-in-progress: false`. A closed pull request or a push can
then cancel a waiting release.
that also starts for other events. By default, a group holds one
running and one waiting run. A third run cancels the waiting one,
also with `cancel-in-progress: false`. A closed pull request or a
push can then cancel a waiting release. `queue: max` keeps every
waiting run.
- A registry with a moving pointer needs one group for all
versions. npm moves `latest` to the version that was published
last. With a group per tag, the publish jobs of two versions
overlap, and the older one can finish last and take `latest`. Give
the publish job one group per registry, with `queue: max`. A
waiting job checks out after the running one ends, so it sees the
newer tag. verwalter then gives the older version another
dist-tag. See [One publish at a time](#one-publish-at-a-time).
- A run without a tag, such as a build on each push, gets a group of
its own: `inputs.tag_name || github.run_id`.
- Check: start the workflow twice for one tag in your head. Does the
Expand Down Expand Up @@ -226,6 +247,27 @@ jobs:
cancel-in-progress: false
```

### One publish at a time

For a registry with a moving pointer, such as `latest` on npm.

```yaml
jobs:
publish:
needs: release
concurrency:
group: npm-publish
cancel-in-progress: false
queue: max
steps:
# The checkout is a step of this job. It runs after the wait,
# so it sees the tags of a release that finished in between.
- uses: actions/checkout@v7
with:
ref: ${{ github.event.pull_request.merge_commit_sha || inputs.ref || github.sha }}
fetch-depth: 0
```

### Pin a run by hand

```yaml
Expand Down
3 changes: 3 additions & 0 deletions skills/release-hardening/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,9 @@ The reference is the verwalter documentation:
| A step after the publish, such as a deploy or a notification, can fail the run. | The run is red after the registry has the version | Put such steps in their own job, after `publish`. Its failure is red, and the release jobs stay green. |
| The workflow trusts the branch name `release/*`. | A release ran that nobody approved | The example runs only for a merged PR from the bot with the verwalter marker in its body. A `workflow_dispatch` trigger is a second door: anyone with write access can run it from any branch. Name who may do that. |
| One version goes to several registries and to release assets. | One registry fails after the release is public. A repair run ends green with nothing done, or fails on the registries that have the version. | `publish.registry` is one per package, and it decides when the draft becomes public. Each further registry is a job of the workflow that asks the registry for the version first. |
| The publish jobs of two versions can run at the same time. | The older version finishes last and takes `latest` on npm. | One concurrency group for the publish job, with `queue: max`. The job checks out after the wait, and verwalter picks the dist-tag from the tags that it sees. |
| A step after the publish writes to one shared place and does not check what was released. | An rc, a release of another package or a release from a maintenance branch replaces the docs site. | Read `package` and `prerelease` from the `releases` output or from the `outcomes` of `publish`. Do not search the output for `-rc.`. |
| The release trigger filters by base branch. | An rc PR into another branch merges. The branch has the version, but no tag and no publish. | The example `release.yml` has no `branches` filter. The condition on its first job decides which PRs release. |

If a weakness is not in the table, read
[docs/release-pitfalls.md](https://github.com/livekit/verwalter/blob/main/docs/release-pitfalls.md).
Expand Down
Loading