diff --git a/.github/workflows/release-prepare.yml b/.github/workflows/release-prepare.yml index 7b7b13f..fa4d7c5 100644 --- a/.github/workflows/release-prepare.yml +++ b/.github/workflows/release-prepare.yml @@ -57,12 +57,12 @@ on: description: "GitHub App slug; the expected bot login is [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 @@ -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 @@ -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 diff --git a/README.md b/README.md index cfef72c..0ae94f5 100644 --- a/README.md +++ b/README.md @@ -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@ # v4.1.0 + uses: chhoumann/obsidian-plugin-workflows/.github/workflows/ci.yml@ # v5.0.0 with: package-manager: pnpm ``` @@ -182,7 +182,7 @@ Shared across all three reusables: | `release-bot-app-slug` | (required) | App slug; the expected bot login is `[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: @@ -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). @@ -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 @@ -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) @@ -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) diff --git a/release-pipeline-plan.md b/release-pipeline-plan.md index fd3ae6a..3288d69 100644 --- a/release-pipeline-plan.md +++ b/release-pipeline-plan.md @@ -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 `[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: ...@` pin. @@ -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. diff --git a/templates/caller-workflows/release-prepare.yml b/templates/caller-workflows/release-prepare.yml index 7f79ede..64c7203 100644 --- a/templates/caller-workflows/release-prepare.yml +++ b/templates/caller-workflows/release-prepare.yml @@ -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 @@ -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 }}