From f46e496877adf1f24479720d1d3cc60618496f52 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Mon, 16 Nov 2026 17:47:38 +0000 Subject: [PATCH 1/3] ci(release): gate release PRs on Apple notarization readiness Add a required-check-ready workflow that calls notarytool history with the release Apple credentials. It fails when the Apple Developer Program License Agreement is missing or expired, with a message naming the Account Holder and both agreement locations. Release PRs created with GITHUB_TOKEN start their pull_request runs in action_required, so add an optional RELEASE_PLEASE_TOKEN (falling back to GITHUB_TOKEN) to let the check and the existing CI run automatically. Also add a publish preflight so manual dispatches fail fast, and document the new gate and token in CONTRIBUTING. --- .../apple-notarization-readiness.yml | 44 +++++++++++++++++++ .github/workflows/publish.yml | 23 ++++++++++ .github/workflows/release.yml | 7 +++ CONTRIBUTING.md | 4 ++ scripts/verifyAppleNotarization.sh | 41 +++++++++++++++++ 5 files changed, 119 insertions(+) create mode 100644 .github/workflows/apple-notarization-readiness.yml create mode 100755 scripts/verifyAppleNotarization.sh diff --git a/.github/workflows/apple-notarization-readiness.yml b/.github/workflows/apple-notarization-readiness.yml new file mode 100644 index 000000000..4a4381b2c --- /dev/null +++ b/.github/workflows/apple-notarization-readiness.yml @@ -0,0 +1,44 @@ +name: Apple Notarization Readiness + +on: + pull_request: + branches: + - main + +permissions: {} + +concurrency: + group: apple-notarization-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + readiness: + name: Apple notarization readiness + # This check must report on every pull request so it can be required on + # `main`. Only release PRs need the macOS-only notary service check; every + # other PR gets a fast no-op on Ubuntu. + runs-on: ${{ startsWith(github.head_ref, 'release-please--') && github.event.pull_request.head.repo.full_name == github.repository && 'macos-latest' || 'ubuntu-latest' }} + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Not a release PR + if: ${{ !startsWith(github.head_ref, 'release-please--') || github.event.pull_request.head.repo.full_name != github.repository }} + run: echo "No Apple notarization check needed for this pull request." + + - name: Checkout trusted verification script + if: ${{ startsWith(github.head_ref, 'release-please--') && github.event.pull_request.head.repo.full_name == github.repository }} + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Never execute pull request code with the Apple release secrets. + # The script comes from the base branch (main), not the release PR. + ref: ${{ github.event.pull_request.base.sha }} + + - name: Verify Apple notarization access + if: ${{ startsWith(github.head_ref, 'release-please--') && github.event.pull_request.head.repo.full_name == github.repository }} + env: + APPLE_ID_USERNAME: ${{ secrets.APPLE_ID_USERNAME }} + APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }} + APPLE_ID_TEAM_ID: ${{ secrets.APPLE_ID_TEAM_ID }} + run: ./scripts/verifyAppleNotarization.sh diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 2f05006e2..85ecfe6f9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -36,8 +36,31 @@ on: permissions: {} jobs: + # Fail in seconds instead of after a build, sign, and notarize cycle. The + # release PR gate should already have caught this, but manual dispatches and + # expired agreements still deserve a clear, early error. + preflight: + name: Apple notarization preflight + runs-on: macos-latest + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Verify Apple notarization access + env: + APPLE_ID_USERNAME: ${{ secrets.APPLE_ID_USERNAME }} + APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }} + APPLE_ID_TEAM_ID: ${{ secrets.APPLE_ID_TEAM_ID }} + run: ./scripts/verifyAppleNotarization.sh + release: name: Publish ${{ matrix.platform }} [electron-builder] + needs: preflight permissions: contents: write strategy: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1c89314a1..6b2923782 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,10 +23,16 @@ jobs: tag_name: ${{ steps.release.outputs.tag_name }} release_pr_title: ${{ steps.pr.outputs.prs_created == 'true' && fromJSON(steps.pr.outputs.pr).title || '' }} steps: + # Release PRs authored by github-actions[bot] (GITHUB_TOKEN) start their + # pull_request runs in an action_required state, so CI and the Apple + # notarization readiness gate wait for a manual approval every release. + # A token from a write-access identity lets those runs start automatically. + # Falls back to GITHUB_TOKEN until the secret is configured. - name: Run release-please (releases) id: release uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 with: + token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }} skip-github-pull-request: true - name: Check for unpublished draft releases @@ -43,6 +49,7 @@ jobs: if: ${{ steps.release.outputs.release_created != 'true' && steps.drafts.outputs.count == '0' }} uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 with: + token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }} skip-github-release: true milestones: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 984cbf39f..e9d355ded 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -222,6 +222,9 @@ Releases are automated with [release-please][release-please]. There is no releas 1. **Merge changes into `main`.** Use [Conventional Commits][conventional-commits] for PR titles (`feat:`, `fix:`, `docs:`, `chore(deps):`, ...). The commit type decides the version bump and the changelog section it lands in. 2. **Review the release PR.** release-please keeps an open `chore: release X.Y.Z` pull request up to date as commits land. It bumps the version in `package.json`, regenerates `CHANGELOG.md`, and updates `sonar.projectVersion` in `sonar-project.properties`. Check the [Renovate Dependency Dashboard][github-dependency-dashboard] for any dependency updates you want to include first. + + Before merging, wait for the **Apple notarization readiness** check. It authenticates to Apple's notary service with the same credentials the release uses and fails when a required Apple agreement is missing or expired. Only the Account Holder can accept the [Apple Developer Program License Agreement](https://developer.apple.com/account) or a pending agreement in [App Store Connect](https://appstoreconnect.apple.com/business/agreements), so surface the failure to them instead of re-running the build. + 3. **Merge the release PR when you are ready to ship.** Merging is the "go" decision. GitHub Actions then automatically: - builds, signs, and notarizes the app on macOS, Windows, and Linux, @@ -238,6 +241,7 @@ No manual milestone creation, renaming, or closing is required. #### 🔐 Release automation permissions +- release-please uses the `RELEASE_PLEASE_TOKEN` secret when it is configured (a fine-grained token or GitHub App token with contents, pull requests, and issues write). Release PRs authored by `github-actions[bot]` via `GITHUB_TOKEN` start their `pull_request` runs in an `action_required` state, so CI and the Apple notarization readiness gate would otherwise wait for a manual approval on every release. Without the secret, the workflow falls back to `GITHUB_TOKEN` and keeps working with that approval prompt. - Packaging and publication use `contents: write`. - The milestone automation uses `issues: write`. - Pull request notification uses `issues: write`, `pull-requests: write`, and `contents: read`. diff --git a/scripts/verifyAppleNotarization.sh b/scripts/verifyAppleNotarization.sh new file mode 100755 index 000000000..4bf32b55f --- /dev/null +++ b/scripts/verifyAppleNotarization.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# Verify that the Apple credentials used by the release pipeline can reach the +# notary service and that all required Apple agreements are in effect. +# +# Apple exposes no API for pending agreement status, so `notarytool history` is +# the only reliable signal: it authenticates without submitting an artifact and +# returns the same 403 that a real notarization submission would. +set -euo pipefail + +: "${APPLE_ID_USERNAME:?APPLE_ID_USERNAME is required}" +: "${APPLE_ID_PASSWORD:?APPLE_ID_PASSWORD is required}" +: "${APPLE_ID_TEAM_ID:?APPLE_ID_TEAM_ID is required}" + +attempts="${NOTARIZATION_CHECK_ATTEMPTS:-4}" +delay_seconds="${NOTARIZATION_CHECK_DELAY_SECONDS:-60}" + +for ((attempt = 1; attempt <= attempts; attempt++)); do + if output=$(xcrun notarytool history \ + --apple-id "${APPLE_ID_USERNAME}" \ + --password "${APPLE_ID_PASSWORD}" \ + --team-id "${APPLE_ID_TEAM_ID}" 2>&1); then + printf '%s\n' "${output}" + echo "Apple notarization access verified." + exit 0 + fi + + printf '%s\n' "${output}" + + if ! grep -q "required agreement is missing or has expired" <<<"${output}"; then + echo "::error title=Apple notarization check failed::notarytool could not authenticate. Check that APPLE_ID_PASSWORD is an app-specific password and APPLE_ID_TEAM_ID matches the Developer ID team." >&2 + exit 1 + fi + + if ((attempt < attempts)); then + echo "Apple agreement is not in effect yet; Apple can take a few minutes to propagate an accepted agreement. Retrying in ${delay_seconds}s..." + sleep "${delay_seconds}" + fi +done + +echo "::error title=Apple agreement missing or expired::Notarization is blocked because a required Apple agreement is missing or expired. The Account Holder (not an Admin) must accept the pending agreement at https://developer.apple.com/account and any pending agreement at https://appstoreconnect.apple.com/business/agreements." >&2 +exit 1 From 57b2fe5b4ec3e7bf01b2afc80b4f7feda66cde31 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Tue, 17 Nov 2026 18:04:38 +0000 Subject: [PATCH 2/3] ci(release): drop optional release-please token and retry loop Keep the workflow approval gate instead of introducing a repo-wide write token. Document the Approve workflows to run step and fail the notarization check on the first 403; a maintainer can re-run it after Apple propagates the accepted agreement. --- .github/workflows/release.yml | 7 ------ CONTRIBUTING.md | 4 ++- scripts/verifyAppleNotarization.sh | 40 ++++++++++++------------------ 3 files changed, 19 insertions(+), 32 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6b2923782..1c89314a1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,16 +23,10 @@ jobs: tag_name: ${{ steps.release.outputs.tag_name }} release_pr_title: ${{ steps.pr.outputs.prs_created == 'true' && fromJSON(steps.pr.outputs.pr).title || '' }} steps: - # Release PRs authored by github-actions[bot] (GITHUB_TOKEN) start their - # pull_request runs in an action_required state, so CI and the Apple - # notarization readiness gate wait for a manual approval every release. - # A token from a write-access identity lets those runs start automatically. - # Falls back to GITHUB_TOKEN until the secret is configured. - name: Run release-please (releases) id: release uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 with: - token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }} skip-github-pull-request: true - name: Check for unpublished draft releases @@ -49,7 +43,6 @@ jobs: if: ${{ steps.release.outputs.release_created != 'true' && steps.drafts.outputs.count == '0' }} uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 with: - token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }} skip-github-release: true milestones: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9d355ded..4fd3aac62 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -225,6 +225,8 @@ Releases are automated with [release-please][release-please]. There is no releas Before merging, wait for the **Apple notarization readiness** check. It authenticates to Apple's notary service with the same credentials the release uses and fails when a required Apple agreement is missing or expired. Only the Account Holder can accept the [Apple Developer Program License Agreement](https://developer.apple.com/account) or a pending agreement in [App Store Connect](https://appstoreconnect.apple.com/business/agreements), so surface the failure to them instead of re-running the build. + release-please opens the PR with `GITHUB_TOKEN`, so GitHub holds its workflow runs for approval. A maintainer with write access must select **Approve workflows to run** before CI and the Apple check execute. + 3. **Merge the release PR when you are ready to ship.** Merging is the "go" decision. GitHub Actions then automatically: - builds, signs, and notarizes the app on macOS, Windows, and Linux, @@ -241,7 +243,7 @@ No manual milestone creation, renaming, or closing is required. #### 🔐 Release automation permissions -- release-please uses the `RELEASE_PLEASE_TOKEN` secret when it is configured (a fine-grained token or GitHub App token with contents, pull requests, and issues write). Release PRs authored by `github-actions[bot]` via `GITHUB_TOKEN` start their `pull_request` runs in an `action_required` state, so CI and the Apple notarization readiness gate would otherwise wait for a manual approval on every release. Without the secret, the workflow falls back to `GITHUB_TOKEN` and keeps working with that approval prompt. +- release-please uses `GITHUB_TOKEN`, so its release PR workflow runs require approval from a user with write access. - Packaging and publication use `contents: write`. - The milestone automation uses `issues: write`. - Pull request notification uses `issues: write`, `pull-requests: write`, and `contents: read`. diff --git a/scripts/verifyAppleNotarization.sh b/scripts/verifyAppleNotarization.sh index 4bf32b55f..a8ec9c093 100755 --- a/scripts/verifyAppleNotarization.sh +++ b/scripts/verifyAppleNotarization.sh @@ -4,38 +4,30 @@ # # Apple exposes no API for pending agreement status, so `notarytool history` is # the only reliable signal: it authenticates without submitting an artifact and -# returns the same 403 that a real notarization submission would. +# returns the same 403 that a real notarization submission would. Retrying here +# would only hide propagation lag; a failed check is easier to understand and +# re-run once the agreement is actually in effect. set -euo pipefail : "${APPLE_ID_USERNAME:?APPLE_ID_USERNAME is required}" : "${APPLE_ID_PASSWORD:?APPLE_ID_PASSWORD is required}" : "${APPLE_ID_TEAM_ID:?APPLE_ID_TEAM_ID is required}" -attempts="${NOTARIZATION_CHECK_ATTEMPTS:-4}" -delay_seconds="${NOTARIZATION_CHECK_DELAY_SECONDS:-60}" - -for ((attempt = 1; attempt <= attempts; attempt++)); do - if output=$(xcrun notarytool history \ - --apple-id "${APPLE_ID_USERNAME}" \ - --password "${APPLE_ID_PASSWORD}" \ - --team-id "${APPLE_ID_TEAM_ID}" 2>&1); then - printf '%s\n' "${output}" - echo "Apple notarization access verified." - exit 0 - fi - +if output=$(xcrun notarytool history \ + --apple-id "${APPLE_ID_USERNAME}" \ + --password "${APPLE_ID_PASSWORD}" \ + --team-id "${APPLE_ID_TEAM_ID}" 2>&1); then printf '%s\n' "${output}" + echo "Apple notarization access verified." + exit 0 +fi - if ! grep -q "required agreement is missing or has expired" <<<"${output}"; then - echo "::error title=Apple notarization check failed::notarytool could not authenticate. Check that APPLE_ID_PASSWORD is an app-specific password and APPLE_ID_TEAM_ID matches the Developer ID team." >&2 - exit 1 - fi +printf '%s\n' "${output}" - if ((attempt < attempts)); then - echo "Apple agreement is not in effect yet; Apple can take a few minutes to propagate an accepted agreement. Retrying in ${delay_seconds}s..." - sleep "${delay_seconds}" - fi -done +if grep -q "required agreement is missing or has expired" <<<"${output}"; then + echo "::error title=Apple agreement missing or expired::Notarization is blocked because a required Apple agreement is missing or expired. The Account Holder (not an Admin) must accept the pending agreement at https://developer.apple.com/account and any pending agreement at https://appstoreconnect.apple.com/business/agreements. If the agreement was just accepted, Apple can take a few minutes to propagate; re-run this check." >&2 + exit 1 +fi -echo "::error title=Apple agreement missing or expired::Notarization is blocked because a required Apple agreement is missing or expired. The Account Holder (not an Admin) must accept the pending agreement at https://developer.apple.com/account and any pending agreement at https://appstoreconnect.apple.com/business/agreements." >&2 +echo "::error title=Apple notarization check failed::notarytool could not authenticate. Check that APPLE_ID_PASSWORD is an app-specific password and APPLE_ID_TEAM_ID matches the Developer ID team." >&2 exit 1 From a498dbb3309477120c8c38af0aa064dcfbe1659f Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Wed, 18 Nov 2026 06:00:23 +0000 Subject: [PATCH 3/3] ci(release): explain the Apple readiness no-op in the step summary Normal pull requests show a green required check without any context. Write a short summary explaining that only release-please PRs verify Apple notarization. --- .github/workflows/apple-notarization-readiness.yml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/.github/workflows/apple-notarization-readiness.yml b/.github/workflows/apple-notarization-readiness.yml index 4a4381b2c..d3106ee5f 100644 --- a/.github/workflows/apple-notarization-readiness.yml +++ b/.github/workflows/apple-notarization-readiness.yml @@ -16,7 +16,8 @@ jobs: name: Apple notarization readiness # This check must report on every pull request so it can be required on # `main`. Only release PRs need the macOS-only notary service check; every - # other PR gets a fast no-op on Ubuntu. + # other PR gets a fast no-op on Ubuntu. Running it everywhere would block + # unrelated work whenever an Apple agreement lapses. runs-on: ${{ startsWith(github.head_ref, 'release-please--') && github.event.pull_request.head.repo.full_name == github.repository && 'macos-latest' || 'ubuntu-latest' }} timeout-minutes: 10 permissions: @@ -24,7 +25,14 @@ jobs: steps: - name: Not a release PR if: ${{ !startsWith(github.head_ref, 'release-please--') || github.event.pull_request.head.repo.full_name != github.repository }} - run: echo "No Apple notarization check needed for this pull request." + run: | + message="Skipped: only release-please pull requests verify Apple notarization." + echo "${message}" + { + echo "### Apple notarization readiness" + echo "" + echo "${message}" + } >> "$GITHUB_STEP_SUMMARY" - name: Checkout trusted verification script if: ${{ startsWith(github.head_ref, 'release-please--') && github.event.pull_request.head.repo.full_name == github.repository }}