Skip to content

Commit 33d5ee0

Browse files
committed
build(release): publish the package from a release workflow
Adds the Release workflow from #190: run by hand on main, it runs CI on the commit, checks the changelog section, packs and verifies the tarball, publishes with provenance through npm trusted publishing, then tags and creates the GitHub release. publishing.md covers the one-time setup and keeps the manual commands as a fallback.
1 parent c28e227 commit 33d5ee0

3 files changed

Lines changed: 183 additions & 24 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ on:
55
branches: [main]
66
pull_request:
77
branches: [main]
8+
# The release runs this same gate on the commit it releases.
9+
workflow_call:
810

911
permissions:
1012
contents: read

‎.github/workflows/release.yml‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
name: Release
2+
3+
# Run by hand from the Actions tab, on main, once CI is green there. See
4+
# apps/docs/src/content/contributing/publishing.md.
5+
on:
6+
workflow_dispatch:
7+
inputs:
8+
version:
9+
description: 'An exact version (0.1.0), or a bump: patch, or minor for a breaking change'
10+
required: true
11+
default: patch
12+
13+
# One release at a time: two would race for the same version.
14+
concurrency:
15+
group: release
16+
cancel-in-progress: false
17+
18+
permissions:
19+
# The version commit, the tag and the GitHub release.
20+
contents: write
21+
# npm provenance and trusted publishing.
22+
id-token: write
23+
24+
jobs:
25+
# The same gate as every push to main, on exactly the commit being released.
26+
ci:
27+
if: github.ref == 'refs/heads/main'
28+
uses: ./.github/workflows/ci.yml
29+
permissions:
30+
contents: read
31+
actions: read
32+
33+
release:
34+
needs: ci
35+
if: github.ref == 'refs/heads/main'
36+
runs-on: ubuntu-latest
37+
timeout-minutes: 30
38+
steps:
39+
- uses: actions/checkout@v7
40+
with:
41+
fetch-depth: 0
42+
43+
- uses: ./.github/actions/setup
44+
with:
45+
registry-url: https://registry.npmjs.org
46+
47+
- name: Version
48+
id: version
49+
env:
50+
INPUT: ${{ inputs.version }}
51+
working-directory: packages/devtools
52+
run: |
53+
if [[ ! "$INPUT" =~ ^(patch|minor|[0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
54+
echo "::error::version must be patch, minor or an exact x.y.z, not '$INPUT'"
55+
exit 1
56+
fi
57+
IFS=. read -r major minor patch <<< "$(node -p "require('./package.json').version")"
58+
case "$INPUT" in
59+
patch) version="$major.$minor.$((patch + 1))" ;;
60+
minor) version="$major.$((minor + 1)).0" ;;
61+
# The same version as now is allowed: running again with the exact version of a
62+
# release that failed part way through finishes it.
63+
*) version="$INPUT" ;;
64+
esac
65+
# Only the version line changes. `npm version` would rewrite the whole file, and turn
66+
# the escaped characters in the description into literal ones.
67+
sed -i -E "s/^( \"version\": )\"[^\"]+\"/\1\"$version\"/" package.json
68+
test "$(node -p "require('./package.json').version")" = "$version"
69+
echo "version=$version" >> "$GITHUB_OUTPUT"
70+
71+
- name: Check the changelog
72+
env:
73+
VERSION: ${{ steps.version.outputs.version }}
74+
run: |
75+
mkdir -p .release
76+
file=packages/devtools/CHANGELOG.md
77+
# This version's section, from its `## x.y.z - date` heading (brackets allowed) to the
78+
# next `## ` heading.
79+
if [ -f "$file" ]; then
80+
awk -v v="$VERSION" '
81+
/^## / {
82+
h = substr($0, 4); sub(/^\[/, "", h); split(h, w, /[] ]/)
83+
inside = (w[1] == v); next
84+
}
85+
inside' "$file" > .release/notes.md
86+
fi
87+
if [ ! -s .release/notes.md ]; then
88+
echo "::error file=$file::Add a '## $VERSION' section to $file before releasing."
89+
exit 1
90+
fi
91+
92+
# `pnpm pack` applies `publishConfig.exports`, and its `prepack` builds the library and the
93+
# panel. `npm publish` of the tarball is what speaks npm's OIDC for trusted publishing.
94+
- name: Build
95+
working-directory: packages/devtools
96+
run: pnpm pack --pack-destination "$GITHUB_WORKSPACE/.release"
97+
98+
# The exact tarball, installed from a local registry into a fresh Angular CLI app and built.
99+
- name: Verify the tarball
100+
run: pnpm verify:publish --tarball="$(ls .release/*.tgz)"
101+
102+
# No token: the package's trusted publisher on npmjs.com names this workflow, and npm
103+
# authenticates the publish through OIDC.
104+
- name: Publish
105+
env:
106+
VERSION: ${{ steps.version.outputs.version }}
107+
run: |
108+
# Already there means an earlier run got this far: skip it, so running again with the
109+
# same exact version finishes a release that failed part way through.
110+
if npm view "@pangular-inspector/devtools@$VERSION" version > /dev/null 2>&1; then
111+
echo "already published: $VERSION"
112+
else
113+
npm publish .release/*.tgz --provenance --access public
114+
fi
115+
116+
- name: Push the version commit and tag
117+
env:
118+
VERSION: ${{ steps.version.outputs.version }}
119+
run: |
120+
git config user.name 'github-actions[bot]'
121+
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
122+
tag="devtools@$VERSION"
123+
if ! git diff --quiet -- packages/devtools/package.json; then
124+
git commit -m "chore(release): $VERSION" -- packages/devtools/package.json
125+
fi
126+
# Pull requests can merge while a release runs. Replay the version commit on top of them
127+
# and tag where it lands. A rebase conflict fails the step rather than guessing.
128+
for attempt in 1 2 3; do
129+
git fetch origin main
130+
git rebase origin/main
131+
git tag -f -a "$tag" -m "$tag"
132+
if git push origin HEAD:main; then break; fi
133+
if [ "$attempt" = 3 ]; then exit 1; fi
134+
done
135+
git push -f origin "refs/tags/$tag"
136+
137+
- name: GitHub release
138+
env:
139+
GH_TOKEN: ${{ github.token }}
140+
VERSION: ${{ steps.version.outputs.version }}
141+
run: |
142+
tag="devtools@$VERSION"
143+
if gh release view "$tag" > /dev/null 2>&1; then
144+
echo "release $tag already exists"
145+
else
146+
gh release create "$tag" --title "$VERSION" --notes-file .release/notes.md
147+
fi

‎apps/docs/src/content/contributing/publishing.md‎

Lines changed: 34 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
22
title: Publishing
3-
description: Bump the version, build, and publish the npm package. Ship the Chrome extension with a fresh UI.
3+
description: Release the npm package from GitHub Actions, check it from a local registry, and ship the Chrome extension with a fresh UI.
44
---
55

66
<ngmd-hero title="Publishing" gradient>
7-
One npm package and one Chrome extension, each with its own version. Bump, build, publish.
7+
One npm package and one Chrome extension, each with its own version. The package releases from a workflow; the extension ships by hand.
88
</ngmd-hero>
99

1010
# Publishing
@@ -55,38 +55,48 @@ The package's `build` script runs two steps:
5555

5656
`prepack` runs `pnpm build`, so every publish builds first.
5757

58-
## Publish the npm package
58+
## Release the npm package
5959

60-
### 1. Bump the version
60+
The **Release** workflow (`.github/workflows/release.yml`) publishes the package from `main`. It runs by hand from the Actions tab and publishes through npm trusted publishing, so no npm token is stored anywhere.
6161

62-
Update `version` in `packages/devtools/package.json`. In the same commit, add a section for the version to `packages/devtools/CHANGELOG.md`. The changelog follows [Keep a Changelog](https://keepachangelog.com), with entries grouped as Upgrade notes, Security fixes, Features and Documentation. Use a message like `chore(release): 0.0.7`.
62+
### Set it up once
6363

64-
### 2. Check the build
65-
66-
Run the checks from [Development setup](./development.md), then build the package without publishing:
67-
68-
```bash
69-
pnpm devtools:build-pkg
70-
```
64+
<ngmd-workflow>
65+
<ngmd-step title="Add the trusted publisher">
66+
On npmjs.com, open the settings of <code>&#64;pangular-inspector/devtools</code>, and under <strong>Trusted publishing</strong> choose GitHub Actions with owner <code>pangular-inspector</code>, repository <code>devtools</code> and workflow <code>release.yml</code>. Leave the environment empty.
67+
</ngmd-step>
68+
<ngmd-step title="Let the workflow push to main">
69+
The workflow pushes the version commit and the tag with the default <code>GITHUB_TOKEN</code>. If a branch protection rule or ruleset guards <code>main</code>, allow GitHub Actions to bypass it, and set <strong>Settings &gt; Actions &gt; Workflow permissions</strong> to read and write.
70+
</ngmd-step>
71+
</ngmd-workflow>
7172

72-
Then check what npm users get. `pnpm verify:publish` publishes the package to a throwaway local registry, creates a fresh Angular CLI app, installs the package from that registry and checks that the hub answers. Pass `--scenario=analog` for an Analog app:
73+
### Each release
7374

74-
```bash
75-
pnpm verify:publish
76-
pnpm verify:publish --scenario=analog
77-
```
75+
1. In a pull request, add a section for the version to `packages/devtools/CHANGELOG.md`, headed `## 1.0.1`. The changelog follows [Keep a Changelog](https://keepachangelog.com). The pull request can also set `version` in `packages/devtools/package.json`; the workflow then leaves it as it is.
76+
2. If `app/` changed since the last release, check that `extension/ui` is current. CI fails when it is stale.
77+
3. Once the pull request is merged and CI is green on `main`, run **Release** from the Actions tab on `main`. Its input is an exact version (`1.0.1`), or `patch`, or `minor`.
7878

79-
### 3. Refresh the extension UI
79+
| Step | What happens |
80+
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
81+
| CI | Runs `ci.yml` on the commit being released, every job included. |
82+
| Version | Sets `version` in `packages/devtools/package.json`. |
83+
| Check the changelog | Fails unless `CHANGELOG.md` has a `## <version>` section. That section becomes the release notes. |
84+
| Build | `pnpm pack` builds the library and the UI into one tarball, with `publishConfig.exports` applied. |
85+
| Verify the tarball | `pnpm verify:publish` installs that tarball into a fresh Angular CLI app from a throwaway local registry, builds it, and checks that the hub answers. |
86+
| Publish | `npm publish --provenance` publishes the tarball on the `latest` tag. |
87+
| Push and tag | Commits `chore(release): <version>` to `main` when the version changed, and tags it `devtools@<version>`. |
88+
| GitHub release | Creates a release for the tag, with the changelog section as its notes. |
8089

81-
If `app/` changed since the last release, run `pnpm extension:build` and commit `extension/ui` before you publish. CI fails when the committed copy is stale.
90+
If the workflow fails before it publishes, nothing has left the runner. Fix the cause and run it again. If it fails after it publishes, run it again with the same exact version, not a bump: it skips the publish when that version is already on npm and finishes the rest.
8291

83-
### 4. Publish
92+
## Publish by hand
8493

85-
```bash
86-
pnpm devtools:publish
87-
```
94+
Use this only if the workflow can't run. It publishes without provenance and needs an npm login with publish rights.
8895

89-
This runs `pnpm --filter @pangular-inspector/devtools publish --access public`. The `prepack` build bundles the library and the UI.
96+
1. Set `version` in `packages/devtools/package.json` and add its section to `packages/devtools/CHANGELOG.md`, in a commit like `chore(release): 1.0.1`.
97+
2. Run the checks from [Development setup](./development.md), then check what npm users get. `pnpm verify:publish` publishes the package to a throwaway local registry, creates a fresh Angular CLI app, installs the package from that registry and checks that the hub answers. Pass `--scenario=analog` for an Analog app.
98+
3. If `app/` changed since the last release, run `pnpm extension:build` and commit `extension/ui`.
99+
4. Publish with `pnpm devtools:publish`, which runs `pnpm --filter @pangular-inspector/devtools publish --access public`. The `prepack` build bundles the library and the UI.
90100

91101
<ngmd-alert severity="important">
92102
<code>pnpm publish</code> checks git before it publishes. Run it from a clean working tree on <code>main</code>.

0 commit comments

Comments
 (0)