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
24 changes: 14 additions & 10 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ jobs:
publish-stable:
name: publish stable packages
runs-on: ubuntu-latest
environment: npm-release
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
steps:
- name: Resolve tag
Expand All @@ -49,7 +50,7 @@ jobs:
echo "npm_tag=$NPM_TAG" >> "$GITHUB_OUTPUT"

- name: Checkout tag
uses: actions/checkout@v4
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
ref: ${{ steps.tag.outputs.tag }}
fetch-depth: 0
Expand Down Expand Up @@ -79,14 +80,15 @@ jobs:
NODE

- name: Setup Bun
uses: oven-sh/setup-bun@v1
uses: oven-sh/setup-bun@f4d14e03ff726c06358e5557344e1da148b56cf7 # v1.2.2
with:
bun-version: latest
bun-version: 1.4.4

- name: Setup Zig
uses: ./.github/actions/setup-zig
with:
version: 0.15.2
cache: 'false'

- name: Install dependencies
run: bun install --frozen-lockfile
Expand Down Expand Up @@ -116,13 +118,13 @@ jobs:
fi

- name: Setup Node.js for npm
uses: actions/setup-node@v4
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: '24.22.1'
registry-url: 'https://registry.npmjs.org'

- name: Ensure current npm for trusted publishing
run: npm install -g npm@latest
run: npm install -g npm@12.2.3

- name: Publish ghostty-web
env:
Expand Down Expand Up @@ -172,6 +174,7 @@ jobs:
publish-next:
name: publish next packages
runs-on: ubuntu-latest
environment: npm-next
# Only ci runs for a push to this repository publish next packages.
if: >-
github.event_name == 'workflow_run' &&
Expand All @@ -180,7 +183,7 @@ jobs:
github.event.workflow_run.head_repository.full_name == github.repository
steps:
- name: Checkout CI head
uses: actions/checkout@v4
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
with:
ref: ${{ github.event.workflow_run.head_sha }}
fetch-depth: 0
Expand All @@ -203,15 +206,16 @@ jobs:

- name: Setup Bun
if: steps.release-commit.outputs.skip != 'true'
uses: oven-sh/setup-bun@v1
uses: oven-sh/setup-bun@f4d14e03ff726c06358e5557344e1da148b56cf7 # v1.2.2
with:
bun-version: latest
bun-version: 1.4.4

- name: Setup Zig
if: steps.release-commit.outputs.skip != 'true'
uses: ./.github/actions/setup-zig
with:
version: 0.15.2
cache: 'false'

- name: Install dependencies
if: steps.release-commit.outputs.skip != 'true'
Expand All @@ -223,14 +227,14 @@ jobs:

- name: Setup Node.js for npm
if: steps.release-commit.outputs.skip != 'true'
uses: actions/setup-node@v4
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: '24.22.1'
registry-url: 'https://registry.npmjs.org'

- name: Ensure current npm for trusted publishing
if: steps.release-commit.outputs.skip != 'true'
run: npm install -g npm@latest
run: npm install -g npm@12.2.3

- name: Compute next version
if: steps.release-commit.outputs.skip != 'true'
Expand Down
8 changes: 4 additions & 4 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@
3. After changes land on `main`, `.github/workflows/release-please.yml` opens or updates one Release Please PR.
4. Merging the Release Please PR creates one `vX.Y.Z-rc.N` tag and a GitHub prerelease while this RC configuration is enabled. The first expected release candidate is `v0.5.0-rc.0`.
5. The Release Please workflow explicitly dispatches `.github/workflows/publish.yml` for the tag because workflows created with `GITHUB_TOKEN` do not reliably trigger follow-up workflows automatically.
6. `publish.yml` validates the tag and source versions, runs the release quality gates, publishes `ghostty-web`, then publishes `@ghostty-web/demo` with its `ghostty-web` dependency pinned to the exact release version.
6. `publish.yml` waits for a maintainer to approve the run in the `npm-release` environment, then validates the tag and source versions, runs the release quality gates, publishes `ghostty-web`, then publishes `@ghostty-web/demo` with its `ghostty-web` dependency pinned to the exact release version.

## Next publishes

`.github/workflows/publish.yml` also publishes `ghostty-web@next` and `@ghostty-web/demo@next` after successful CI on `main`. Release-only squash commits whose subject matches `chore(release): ...` are skipped so version/changelog-only release PR merges do not create noisy prereleases.
`.github/workflows/publish.yml` also publishes `ghostty-web@next` and `@ghostty-web/demo@next` after successful CI on `main`, from the `npm-next` environment. Release-only squash commits whose subject matches `chore(release): ...` are skipped so version/changelog-only release PR merges do not create noisy prereleases.

Stable, release-candidate, and `next` publishing intentionally live in this single workflow file because npm trusted publishing is configured against a workflow identity.

Expand All @@ -28,13 +28,13 @@ When the pipeline has been test-driven successfully and maintainers are ready fo
## Manual recovery

- Rerun `Release Please` on `main` to recreate or update a release PR.
- Dispatch `publish.yml` manually with an existing `vX.Y.Z-rc.N` or `vX.Y.Z` tag to retry npm publishing.
- Dispatch `publish.yml` manually with an existing `vX.Y.Z-rc.N` or `vX.Y.Z` tag to retry npm publishing. The run needs the same approval.
- Publish jobs are idempotent: if a package version already exists on npm, the workflow skips publishing and attempts to repair the matching dist-tag (`rc` for `0.5.0-rc.0`, `latest` for stable versions).

## Required admin setup

Before the first automated stable release:

- Configure npm trusted publishers for both `ghostty-web` and `@ghostty-web/demo` for `.github/workflows/publish.yml`.
- Configure npm trusted publishers for both `ghostty-web` and `@ghostty-web/demo` for `.github/workflows/publish.yml`, one for each of the `npm-release` and `npm-next` environments.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Configure required reviewers for the release environment

In repositories where npm-release has not already been configured, this runbook never tells an administrator to add required reviewers, so the promised approval gate is not enforced. GitHub automatically creates a referenced environment without protection rules, and merely setting environment: npm-release does not require approval; the tag-triggered job can therefore publish immediately. Add creation of the environment and its required-reviewer protection to the admin setup. GitHub documents the auto-creation behavior and lack of default protections here.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Enable direct publishing for every trusted publisher

For the new environment-specific trusted publishers created by following this instruction, the workflow's npm publish commands will be rejected unless the administrator explicitly enables direct publishing. Since September 3, 2026, new npm trusted-publisher configurations allow staged publishing by default and require opting into npm publish; npm dist-tag also needs its own permission for the documented recovery path. Update the setup step to require both allowed actions for all four package/environment configurations. The npm trusted-publishing documentation describes these action permissions and defaults.

Useful? React with 👍 / 👎.

- Enable squash merging, disable merge commits and rebase merging, and set squash commit titles to use the pull request title.
- Require the `pr-title`, `fmt`, `lint`, `type check`, `test`, and `build` checks before merge; require merge-group variants too if merge queue is enabled.
Loading