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
38 changes: 34 additions & 4 deletions .github/workflows/release-prepare.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,12 @@ on:
description: "GitHub App slug; the expected bot login is <slug>[bot]."
type: string
required: true
app-id:
description: "GitHub App id (a repository variable value) for the release bot."
client-id:
description: "GitHub App client ID (a repository variable value) for the release bot."
type: string
required: true
dry-run:
description: "Plan only: compute version + notes, skip opening a PR."
description: "Plan only: compute version + notes and check the App credentials, skip opening a PR."
type: boolean
required: false
default: false
Expand Down Expand Up @@ -294,6 +294,36 @@ jobs:
if-no-files-found: error
retention-days: 1

check-app:
name: Check release-bot App
if: inputs.dry-run
runs-on: ubuntu-latest
permissions: {}
steps:
- name: Harden Runner
uses: step-security/harden-runner@ccd8616d44fd3846e67624a50d5aad6d37bf2d25 # v2.22.1
with:
egress-policy: audit

- name: Generate release-bot token
id: app-token
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
client-id: ${{ inputs.client-id }}
private-key: ${{ secrets.release-app-private-key }}
permission-contents: read

- name: Confirm App slug
env:
APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
EXPECTED_APP_SLUG: ${{ inputs.release-bot-app-slug }}
run: |
if [ "$APP_SLUG" != "$EXPECTED_APP_SLUG" ]; then
echo "::error::Minted App slug $APP_SLUG does not match release-bot-app-slug $EXPECTED_APP_SLUG."
exit 1
fi
echo "Minted a token for $APP_SLUG."

open-pr:
name: Open release PR
needs: plan
Expand All @@ -318,7 +348,7 @@ jobs:
id: app-token
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
app-id: ${{ inputs.app-id }}
client-id: ${{ inputs.client-id }}
private-key: ${{ secrets.release-app-private-key }}
permission-contents: write
permission-pull-requests: write
Expand Down
31 changes: 16 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ A consumer references a workflow by path and pins a ref:
```yaml
jobs:
ci:
uses: chhoumann/obsidian-plugin-workflows/.github/workflows/ci.yml@<full-commit-sha> # v4.1.0
uses: chhoumann/obsidian-plugin-workflows/.github/workflows/ci.yml@<full-commit-sha> # v5.0.0
with:
package-manager: pnpm
```
Expand Down Expand Up @@ -182,7 +182,7 @@ Shared across all three reusables:
| `release-bot-app-slug` | (required) | App slug; the expected bot login is `<slug>[bot]`. |

`release-prepare.yml` adds: `target-sha` (empty = default-branch head),
`node-version`, `release-policy` (below), `app-id` (a repo **variable** value),
`node-version`, `release-policy` (below), `client-id` (a repo **variable** value),
the `release-app-private-key` **secret**, and `dry-run`. `release-validate.yml`
adds: `pr-number`, `release-merger-login` (empty = repo owner), and
`release-workflow` (the consumer workflow to dispatch). `release.yml` adds:
Expand Down Expand Up @@ -262,9 +262,10 @@ control and can be made a branch-protection bypass actor. Per repo:
and write**. No account permissions, no webhook.
3. Generate a private key (downloads a `.pem`).
4. Install the App on the plugin repo only (Install App -> select the repo).
5. In the repo: add a variable `RELEASE_APP_ID` (Settings -> Secrets and variables
-> Actions -> Variables) with the App's numeric id, and a secret
`RELEASE_APP_PRIVATE_KEY` with the full `.pem` contents.
5. In the repo: add a variable `RELEASE_APP_CLIENT_ID` (Settings -> Secrets and
variables -> Actions -> Variables) with the App's **Client ID** (shown on the
App's General page, e.g. `Iv23li...`), and a secret `RELEASE_APP_PRIVATE_KEY`
with the full `.pem` contents.
6. If the default branch is protected, add the App as an allowed bypass/merge actor
as your ruleset requires (the maintainer still merges the PR; the App only
authors it).
Expand All @@ -274,10 +275,10 @@ control and can be made a branch-protection bypass actor. Per repo:
Before a repo's first real release, dispatch the **Prepare release** workflow
manually (Actions -> Prepare release -> Run workflow) with **dryRun** checked. The
stub forwards it as the reusable workflow's `dry-run` input. The plan job computes
the version and notes and uploads them as an artifact; the open-PR job is skipped,
so nothing is pushed and no App call is made (dummy `app-id` / slug are fine for a
pure planning check). Confirm the planned version and notes look right. Dispatch
with `dryRun` again any time to preview the next release.
the version and notes and uploads them as an artifact, and a check job mints a
read-only App token and confirms its slug matches `release-bot-app-slug`. The
open-PR job is skipped, so nothing is pushed. Confirm the planned version and notes
look right. Dispatch with `dryRun` again any time to preview the next release.

### Recovery

Expand Down Expand Up @@ -317,7 +318,7 @@ workflow state.

1. Ensure the current released version is tagged and has a published GitHub release
(the planner requires a tagged baseline).
2. Create and install the release-bot App; set `RELEASE_APP_ID` +
2. Create and install the release-bot App; set `RELEASE_APP_CLIENT_ID` +
`RELEASE_APP_PRIVATE_KEY` (above).
3. Copy the three caller stubs from
[`templates/caller-workflows/`](./templates/caller-workflows)
Expand Down Expand Up @@ -385,12 +386,12 @@ per-file guide in [`templates/README.md`](./templates/README.md):
Consumers pin a commit SHA with a version comment, so every release needs an
immutable semver tag for that comment and for Dependabot to compare against.

- Tag each release `v4.1.0`, `v4.2.0`, ... The "Immutable release tags" ruleset
- Tag each release `v5.0.0`, `v5.1.0`, ... The "Immutable release tags" ruleset
blocks moving or deleting any `v*.*.*` tag.
- Keep the major tag (`v4`) pointed at the latest compatible release for anyone
still on tag pins: `git tag -f v4 v4.2.0 && git push -f origin v4`.
- Cut `v5` only for a breaking change to a workflow's input surface or behavior.
Leave `v4` in place so unmigrated consumers keep working, then migrate them.
- Keep the major tag (`v5`) pointed at the latest compatible release for anyone
still on tag pins: `git tag -f v5 v5.1.0 && git push -f origin v5`.
- Cut `v6` only for a breaking change to a workflow's input surface or behavior.
Leave `v5` in place so unmigrated consumers keep working, then migrate them.

## Migration checklist (CI and quality workflows)

Expand Down
10 changes: 5 additions & 5 deletions release-pipeline-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ Genuinely per-repo values become `workflow_call` inputs. The load-bearing ones:
- **release-bot-app-slug** - the per-repo App slug; the expected bot login is
`<slug>[bot]`. prepare cross-checks the minted token's slug against it;
validate and release check `pull.user.login` against it.
- **app-id** (var) + **release-app-private-key** (secret) - mint the App token in
- **client-id** (var) + **release-app-private-key** (secret) - mint the App token in
prepare for PR/commit authorship.
- **workflows-ref / workflows-repository** - the pin + repo for the scripts
checkout; `workflows-ref` is kept in sync with the `uses: ...@<ref>` pin.
Expand Down Expand Up @@ -191,12 +191,12 @@ otherwise. Layered checks:
`package-manager: pnpm`, `release-assets` including `styles.css`,
`node-version: 24`.

Each repo needs its App created and installed, and `RELEASE_APP_ID` (var) +
Each repo needs its App created and installed, and `RELEASE_APP_CLIENT_ID` (var) +
`RELEASE_APP_PRIVATE_KEY` (secret) set before its first release. See the README.

## Dry-run / smoke test before a first real release

`release-prepare.yml` exposes a `dry-run` input: the plan job computes the version
and notes and uploads them as an artifact, and the open-pr job is skipped, so a
consumer can confirm planning works end to end without opening a PR or touching an
App. The README documents driving it via the `workflow_dispatch` escape hatch.
and notes and uploads them as an artifact, a check job mints a read-only App token
and confirms its slug, and the open-pr job is skipped, so a consumer can confirm
planning and the App credentials work end to end without opening a PR. The README documents driving it via the `workflow_dispatch` escape hatch.
5 changes: 3 additions & 2 deletions templates/caller-workflows/release-prepare.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
# default-branch head and opens/refreshes the standing release PR.
#
# Escape hatch: workflow_dispatch lets you plan manually without waiting for a
# CI completion. Set dryRun to plan without opening or refreshing the release PR.
# CI completion. Set dryRun to plan and check the App credentials without opening
# or refreshing the release PR.

name: Prepare release

Expand Down Expand Up @@ -57,7 +58,7 @@ jobs:
node-version: "22"
target-sha: ${{ github.event.workflow_run.head_sha || inputs.targetSha }}
release-bot-app-slug: podnotes-release-bot
app-id: ${{ vars.RELEASE_APP_ID }}
client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
dry-run: ${{ inputs.dryRun == true }}
secrets:
release-app-private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
Loading