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
4 changes: 3 additions & 1 deletion .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@ jobs:
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Check editorconfig
- name: Install editorconfig-checker
uses: editorconfig-checker/action-editorconfig-checker@main
- name: Check editorconfig
run: editorconfig-checker
package-json:
runs-on: ubuntu-latest
name: package.json
Expand Down
26 changes: 13 additions & 13 deletions skills/setup-simple-release-action/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -384,23 +384,23 @@ On push and comment events `inputs.snapshot` is empty, so `check` runs as usual

Finish with a checklist of the steps that cannot be automated:

1. **Allow pull request creation**: repository **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests**. Without it the `pull-request` job fails with "GitHub Actions is not permitted to create or approve pull requests". With the GitHub CLI:
1. **Allow pull request creation**: repository **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests**. Without it the `pull-request` job fails with "GitHub Actions is not permitted to create or approve pull requests". With the GitHub CLI:

```bash
gh api -X PUT repos/{owner}/{repo}/actions/permissions/workflow \
-F can_approve_pull_request_reviews=true
```
```bash
gh api -X PUT repos/{owner}/{repo}/actions/permissions/workflow \
-F can_approve_pull_request_reviews=true
```

2. **npm authentication** — with the token flow, an `NPM_TOKEN` secret: an npm automation (granular) token with publish permission for the packages. With trusted publishing, no secret; instead register the trusted publisher for every published package on npmjs.com — package **Settings → Trusted Publisher → GitHub Actions**: the organization or user, the repository, the workflow filename `release.yml`, and optionally an environment — or with the npm CLI (11.15 or later, two-factor authentication required):
2. **npm authentication** — with the token flow, an `NPM_TOKEN` secret: an npm automation (granular) token with publish permission for the packages. With trusted publishing, no secret; instead register the trusted publisher for every published package on npmjs.com — package **Settings → Trusted Publisher → GitHub Actions**: the organization or user, the repository, the workflow filename `release.yml`, and optionally an environment — or with the npm CLI (11.15 or later, two-factor authentication required):

```bash
npm trust github <package> --repository <owner>/<repo> --file release.yml --allow-publish
```
```bash
npm trust github <package> --repository <owner>/<repo> --file release.yml --allow-publish
```

A package that was never published has no settings to register on: publish its first version with a token first. Neither is needed for GitHub Packages (the workflow token is used) or for non-publishing projects.
3. **Squash-merge release pull requests** — the release is recognized by the `chore(release): ...` commit title on the branch head. A regular merge commit hides it and the release job will not run. Recommend enabling squash merging for the repository.
4. **The first release** — after the setup is merged, the next push of a releasable commit (or the setup push itself) opens a release pull request. When no release tags exist yet, the version is taken from the manifest as is and the changelog covers the whole history.
5. **Reshaping a pending release** — a comment on the release pull request starting with `!simple-release/set-options` followed by a JSON code block (for example `{"bump": {"as": "major"}}`) rebuilds it with those options. A `!simple-release/set-preamble` comment (optionally followed by a full package name to target one package in a monorepo) inserts the markdown after it into the changelog. Both are documented in the cheatsheet included in every release pull request body.
A package that was never published has no settings to register on: publish its first version with a token first. Neither is needed for GitHub Packages (the workflow token is used) or for non-publishing projects.
3. **Squash-merge release pull requests** — the release is recognized by the `chore(release): ...` commit title on the branch head. A regular merge commit hides it and the release job will not run. Recommend enabling squash merging for the repository.
4. **The first release** — after the setup is merged, the next push of a releasable commit (or the setup push itself) opens a release pull request. When no release tags exist yet, the version is taken from the manifest as is and the changelog covers the whole history.
5. **Reshaping a pending release** — a comment on the release pull request starting with `!simple-release/set-options` followed by a JSON code block (for example `{"bump": {"as": "major"}}`) rebuilds it with those options. A `!simple-release/set-preamble` comment (optionally followed by a full package name to target one package in a monorepo) inserts the markdown after it into the changelog. Both are documented in the cheatsheet included in every release pull request body.

Suggest a hidden-type commit message for the setup itself, such as `ci: set up release automation`.

Expand Down
10 changes: 5 additions & 5 deletions website/src/content/docs/github-action/maintenance-branches.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ After a new major ships, the previous one usually still has users. **Maintenance

The full lifecycle on an example:

1. The project is released as `1.1.0`. A breaking change lands and the release pull request ships `2.0.0` — the action creates the `v1` branch from the `v1.1.0` tag.
2. A `fix: ...` commit is pushed to `v1` — the action opens a release pull request targeting `v1` with the `1.1.1` bump.
3. The pull request is squash-merged — `1.1.1` is tagged and published from the maintenance branch:
- the package goes to the `release-1.x` npm dist-tag, `latest` stays on `2.0.0`;
- the GitHub release is created without the **Latest** mark.
1. The project is released as `1.1.0`. A breaking change lands and the release pull request ships `2.0.0` — the action creates the `v1` branch from the `v1.1.0` tag.
2. A `fix: ...` commit is pushed to `v1` — the action opens a release pull request targeting `v1` with the `1.1.1` bump.
3. The pull request is squash-merged — `1.1.1` is tagged and published from the maintenance branch:
- the package goes to the `release-1.x` npm dist-tag, `latest` stays on `2.0.0`;
- the GitHub release is created without the **Latest** mark.

## Setup

Expand Down
186 changes: 93 additions & 93 deletions website/src/content/docs/github-action/release-automation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,99 +17,99 @@ The main flow keeps a **release pull request** up to date and releases it on mer

<Steps>

1. Create a [config](/getting-started/configuration/) describing your project in the repository root:

```json title=".simple-release.json"
{
"project": ["@simple-release/pnpm#PnpmWorkspacesProject", {
"mode": "fixed"
}]
}
```

The action installs the addon named in the query by itself — no dependencies to add to your project.

2. Create the release workflow:

```yaml title=".github/workflows/release.yml"
name: Release
on:
issue_comment:
types: [created, deleted]
push:
branches:
- main
jobs:
check:
runs-on: ubuntu-latest
name: Context check
permissions:
contents: read
outputs:
continue: ${{ steps.check.outputs.continue }}
workflow: ${{ steps.check.outputs.workflow }}
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Context check
id: check
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: check
github-token: ${{ secrets.GITHUB_TOKEN }}
pull-request:
runs-on: ubuntu-latest
name: Pull request
needs: check
if: needs.check.outputs.workflow == 'pull-request'
permissions:
contents: write
pull-requests: write
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Create or update pull request
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: pull-request
github-token: ${{ secrets.GITHUB_TOKEN }}
release:
runs-on: ubuntu-latest
name: Release
needs: check
if: needs.check.outputs.workflow == 'release'
permissions:
contents: write
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Install pnpm
uses: pnpm/action-setup@v6
with:
version: 11
- name: Install Node.js
uses: actions/setup-node@v6
with:
node-version: 22
cache: 'pnpm'
registry-url: 'https://registry.npmjs.org'
- name: Install dependencies
run: pnpm install
- name: Release
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: release
github-token: ${{ secrets.GITHUB_TOKEN }}
npm-token: ${{ secrets.NPM_TOKEN }}
```

The three jobs map to the action [workflows](/github-action/#workflows): `check` decides what should run for the current event, `pull-request` maintains the release pull request, and `release` runs on the merged release commit — it creates the tags, publishes the packages, and creates the GitHub release.

The `release` job publishes with the `NPM_TOKEN` secret — an npm automation token with publish permission for the packages. To publish without any secret, switch the job to [trusted publishing](/github-action/trusted-publishing/).

3. Allow the action to create pull requests: in the repository **Settings → Actions → General**, enable **Allow GitHub Actions to create and approve pull requests**. Without it the `pull-request` job fails with a "GitHub Actions is not permitted to create or approve pull requests" error.

4. Push a `feat: ...` or `fix: ...` commit to `main` — the release pull request appears. Merge it with **squash** to release.
1. Create a [config](/getting-started/configuration/) describing your project in the repository root:

```json title=".simple-release.json"
{
"project": ["@simple-release/pnpm#PnpmWorkspacesProject", {
"mode": "fixed"
}]
}
```

The action installs the addon named in the query by itself — no dependencies to add to your project.

2. Create the release workflow:

```yaml title=".github/workflows/release.yml"
name: Release
on:
issue_comment:
types: [created, deleted]
push:
branches:
- main
jobs:
check:
runs-on: ubuntu-latest
name: Context check
permissions:
contents: read
outputs:
continue: ${{ steps.check.outputs.continue }}
workflow: ${{ steps.check.outputs.workflow }}
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Context check
id: check
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: check
github-token: ${{ secrets.GITHUB_TOKEN }}
pull-request:
runs-on: ubuntu-latest
name: Pull request
needs: check
if: needs.check.outputs.workflow == 'pull-request'
permissions:
contents: write
pull-requests: write
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Create or update pull request
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: pull-request
github-token: ${{ secrets.GITHUB_TOKEN }}
release:
runs-on: ubuntu-latest
name: Release
needs: check
if: needs.check.outputs.workflow == 'release'
permissions:
contents: write
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Install pnpm
uses: pnpm/action-setup@v6
with:
version: 11
- name: Install Node.js
uses: actions/setup-node@v6
with:
node-version: 22
cache: 'pnpm'
registry-url: 'https://registry.npmjs.org'
- name: Install dependencies
run: pnpm install
- name: Release
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: release
github-token: ${{ secrets.GITHUB_TOKEN }}
npm-token: ${{ secrets.NPM_TOKEN }}
```

The three jobs map to the action [workflows](/github-action/#workflows): `check` decides what should run for the current event, `pull-request` maintains the release pull request, and `release` runs on the merged release commit — it creates the tags, publishes the packages, and creates the GitHub release.

The `release` job publishes with the `NPM_TOKEN` secret — an npm automation token with publish permission for the packages. To publish without any secret, switch the job to [trusted publishing](/github-action/trusted-publishing/).

3. Allow the action to create pull requests: in the repository **Settings → Actions → General**, enable **Allow GitHub Actions to create and approve pull requests**. Without it the `pull-request` job fails with a "GitHub Actions is not permitted to create or approve pull requests" error.

4. Push a `feat: ...` or `fix: ...` commit to `main` — the release pull request appears. Merge it with **squash** to release.

</Steps>

Expand Down
100 changes: 50 additions & 50 deletions website/src/content/docs/github-action/trusted-publishing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,56 +20,56 @@ import { Aside, Steps } from '@astrojs/starlight/components'

<Steps>

1. Register the trusted publisher for each package on npmjs.com — package **Settings → Trusted Publisher → GitHub Actions**: the organization or user, the repository name, the workflow filename `release.yml`, and optionally a GitHub environment. The same from the npm CLI (11.15 or later, two-factor authentication required):

```sh frame="none"
npm trust github your-package --repository your-org/your-repo --file release.yml --allow-publish
```

Nothing is validated at this point — a typo in the repository or the filename shows up only as an authentication error at publish time.

2. Change the `release` job of the [release workflow](/github-action/release-automation/): grant it the `id-token: write` permission, drop `registry-url` from `actions/setup-node` and `npm-token` from the action step — there is no token to pass — and use Node.js 24:

```yaml title=".github/workflows/release.yml" {8,20-21,25}
jobs:
# ...the check and pull-request jobs stay as they are
release:
runs-on: ubuntu-latest
name: Release
needs: check
if: needs.check.outputs.workflow == 'release'
permissions:
contents: write
id-token: write
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Install pnpm
uses: pnpm/action-setup@v6
with:
version: 11
- name: Install Node.js
uses: actions/setup-node@v6
with:
node-version: 24
cache: 'pnpm'
- name: Install dependencies
run: pnpm install
- name: Release
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: release
github-token: ${{ secrets.GITHUB_TOKEN }}
```

3. Squash-merge the next release pull request. The publish step of the release job now reports the OIDC publish and the provenance statement:

```text frame="none"
Publishing with command: pnpm publish --access public --recursive --no-git-checks
npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
npm notice publish Signed provenance statement with source and build information from GitHub Actions
npm notice publish Provenance statement published to transparency log: https://search.sigstore.dev/?logIndex=...
```
1. Register the trusted publisher for each package on npmjs.com — package **Settings → Trusted Publisher → GitHub Actions**: the organization or user, the repository name, the workflow filename `release.yml`, and optionally a GitHub environment. The same from the npm CLI (11.15 or later, two-factor authentication required):

```sh frame="none"
npm trust github your-package --repository your-org/your-repo --file release.yml --allow-publish
```

Nothing is validated at this point — a typo in the repository or the filename shows up only as an authentication error at publish time.

2. Change the `release` job of the [release workflow](/github-action/release-automation/): grant it the `id-token: write` permission, drop `registry-url` from `actions/setup-node` and `npm-token` from the action step — there is no token to pass — and use Node.js 24:

```yaml title=".github/workflows/release.yml" {8,20-21,25}
jobs:
# ...the check and pull-request jobs stay as they are
release:
runs-on: ubuntu-latest
name: Release
needs: check
if: needs.check.outputs.workflow == 'release'
permissions:
contents: write
id-token: write
steps:
- name: Checkout the repository
uses: actions/checkout@v7
- name: Install pnpm
uses: pnpm/action-setup@v6
with:
version: 11
- name: Install Node.js
uses: actions/setup-node@v6
with:
node-version: 24
cache: 'pnpm'
- name: Install dependencies
run: pnpm install
- name: Release
uses: TrigenSoftware/simple-release-action@v2
with:
workflow: release
github-token: ${{ secrets.GITHUB_TOKEN }}
```

3. Squash-merge the next release pull request. The publish step of the release job now reports the OIDC publish and the provenance statement:

```text frame="none"
Publishing with command: pnpm publish --access public --recursive --no-git-checks
npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
npm notice publish Signed provenance statement with source and build information from GitHub Actions
npm notice publish Provenance statement published to transparency log: https://search.sigstore.dev/?logIndex=...
```

</Steps>

Expand Down
8 changes: 5 additions & 3 deletions website/src/styles/global.css
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,11 @@

& .expressive-code .frame {
--code-background: var(--sl-color-bg-nav);
/* Retint Expressive Code's frame chrome (tab, title bar) to the warm theme
so the title tab blends with the code background instead of the stock
near-black GitHub tab. References --code-background so light mode follows. */
/**
* Retint Expressive Code's frame chrome (tab, title bar) to the warm theme
* so the title tab blends with the code background instead of the stock
* near-black GitHub tab. References --code-background so light mode follows.
*/
--ec-frm-edBg: var(--code-background);
--ec-frm-edActTabBg: var(--code-background);
--ec-frm-trmTtbBg: var(--code-background);
Expand Down
Loading