From 7c5f683f10ab5bf6dec28f98f9d38b43ea743609 Mon Sep 17 00:00:00 2001 From: Repro Date: Tue, 1 Sep 2026 13:03:32 +0300 Subject: [PATCH 1/3] ci: use PUBLISH_DOCS_TOKEN for gh-pages deploys The gh-pages branch is protected by an org-wide ruleset that blocks direct pushes (requires a PR). The default GITHUB_TOKEN identity used by the gh-pages deploy step is not on that ruleset's bypass list, so every docs deploy has been failing with: remote: error: GH013: Repository rule violations found for refs/heads/gh-pages. remote: - Changes must be made through a pull request. Prior to #421, the workflow used personal_token: ${{ secrets.PUBLISH_DOCS_TOKEN }} instead of GITHUB_TOKEN, and that token's identity is allowed to bypass the ruleset (confirmed by successful gh-pages deploys through March 2025, well after the ruleset was created in May 2024). #421 switched to GITHUB_TOKEN as an intentional deviation from the module template, which is what broke this. Revert to PUBLISH_DOCS_TOKEN across the call chain, matching the current metamask-module-template: - publish-docs.yml: require PUBLISH_DOCS_TOKEN secret, use personal_token instead of github_token in the deploy step - publish-main-docs.yml / publish-rc-docs.yml: forward PUBLISH_DOCS_TOKEN to publish-docs.yml - publish-release.yml: require PUBLISH_DOCS_TOKEN secret, forward it to both gh-pages jobs - main.yml: forward PUBLISH_DOCS_TOKEN to publish-release.yml --- .github/workflows/main.yml | 1 + .github/workflows/publish-docs.yml | 7 ++++++- .github/workflows/publish-main-docs.yml | 2 ++ .github/workflows/publish-rc-docs.yml | 2 ++ .github/workflows/publish-release.yml | 6 ++++++ 5 files changed, 17 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 964b07ce..5388f692 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -124,3 +124,4 @@ jobs: secrets: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} + PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index ff8fe22d..3f2ea6cf 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -6,6 +6,9 @@ on: destination_dir: required: true type: string + secrets: + PUBLISH_DOCS_TOKEN: + required: true jobs: publish-docs-to-gh-pages: @@ -28,6 +31,8 @@ jobs: - name: Deploy to `${{ inputs.destination_dir }}` directory of `gh-pages` branch uses: peaceiris/actions-gh-pages@de7ea6f8efb354206b205ef54722213d99067935 with: - github_token: ${{ secrets.GITHUB_TOKEN }} + # This `PUBLISH_DOCS_TOKEN` needs to be manually set per-repository. + # Look in the repository settings under "Environments", and set this token in the `github-pages` environment. + personal_token: ${{ secrets.PUBLISH_DOCS_TOKEN }} publish_dir: ./docs destination_dir: ${{ inputs.destination_dir }} diff --git a/.github/workflows/publish-main-docs.yml b/.github/workflows/publish-main-docs.yml index 1fe2a270..b9bbbefc 100644 --- a/.github/workflows/publish-main-docs.yml +++ b/.github/workflows/publish-main-docs.yml @@ -12,3 +12,5 @@ jobs: uses: ./.github/workflows/publish-docs.yml with: destination_dir: staging + secrets: + PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} diff --git a/.github/workflows/publish-rc-docs.yml b/.github/workflows/publish-rc-docs.yml index 85725a65..dc8573d2 100644 --- a/.github/workflows/publish-rc-docs.yml +++ b/.github/workflows/publish-rc-docs.yml @@ -30,3 +30,5 @@ jobs: needs: get-release-version with: destination_dir: rc-${{ needs.get-release-version.outputs.release-version }} + secrets: + PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml index 5cc473ac..6447a0d1 100644 --- a/.github/workflows/publish-release.yml +++ b/.github/workflows/publish-release.yml @@ -7,6 +7,8 @@ on: required: false SLACK_WEBHOOK_URL: required: true + PUBLISH_DOCS_TOKEN: + required: true permissions: contents: read @@ -115,6 +117,8 @@ jobs: uses: ./.github/workflows/publish-docs.yml with: destination_dir: ${{ needs.get-release-version.outputs.RELEASE_VERSION }} + secrets: + PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} publish-release-to-latest-gh-pages: name: Publish docs to `latest` directory of `gh-pages` branch @@ -124,6 +128,8 @@ jobs: uses: ./.github/workflows/publish-docs.yml with: destination_dir: latest + secrets: + PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} publish-release: name: Publish to GitHub From 77157cad5d50dc91b14263e041cdeb4e5f2fae1a Mon Sep 17 00:00:00 2001 From: Repro Date: Tue, 1 Sep 2026 13:05:42 +0300 Subject: [PATCH 2/3] Remove unnecessary comment --- .github/workflows/publish-docs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 3f2ea6cf..9421b5ed 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -31,8 +31,6 @@ jobs: - name: Deploy to `${{ inputs.destination_dir }}` directory of `gh-pages` branch uses: peaceiris/actions-gh-pages@de7ea6f8efb354206b205ef54722213d99067935 with: - # This `PUBLISH_DOCS_TOKEN` needs to be manually set per-repository. - # Look in the repository settings under "Environments", and set this token in the `github-pages` environment. personal_token: ${{ secrets.PUBLISH_DOCS_TOKEN }} publish_dir: ./docs destination_dir: ${{ inputs.destination_dir }} From 1e2be09b5091a2e1484d0ced684b36a0266c3ab1 Mon Sep 17 00:00:00 2001 From: Repro Date: Tue, 1 Sep 2026 13:25:46 +0300 Subject: [PATCH 3/3] ci: use OIDC token-exchange for gh-pages deploys instead of static token Switch the gh-pages deploy from the static PUBLISH_DOCS_TOKEN secret to the org's OIDC token-exchange service, matching the pattern already used by MetaMask/snaps (publish-github-pages.yml). Each job requests a short-lived contents:write token via MetaMask/github-tools/.github/actions/get-token@v1, which exchanges the job's signed OIDC identity token against ${{ vars.TOKEN_EXCHANGE_URL }} (an org variable already inherited by this repo). That token is fed into peaceiris/actions-gh-pages as personal_token, replacing the static PUBLISH_DOCS_TOKEN secret used in the previous commit. Benefits over the static-token approach: - No long-lived secret stored in the github-pages environment. - Token is minted per-run and expires in minutes. - Nothing to rotate or accidentally leave stale (this is what caused the original outage: PUBLISH_DOCS_TOKEN silently going unused for months after #421 switched to GITHUB_TOKEN). Changes: - publish-docs.yml: add id-token: write permission, add "Get access token" step using MetaMask/github-tools/.github/actions/get-token@v1, use the exchanged token as personal_token instead of secrets.PUBLISH_DOCS_TOKEN. Drop the now-unused PUBLISH_DOCS_TOKEN secret declaration. - publish-main-docs.yml / publish-rc-docs.yml: update caller permissions to contents: read + id-token: write; drop the PUBLISH_DOCS_TOKEN secret forwarding (no longer needed). - publish-release.yml: same permission update for both gh-pages jobs; drop the PUBLISH_DOCS_TOKEN secret requirement and forwarding. - main.yml: drop the now-unused PUBLISH_DOCS_TOKEN forward to publish-release.yml. --- .github/workflows/main.yml | 1 - .github/workflows/publish-docs.yml | 15 ++++++++++----- .github/workflows/publish-main-docs.yml | 5 ++--- .github/workflows/publish-rc-docs.yml | 5 ++--- .github/workflows/publish-release.yml | 12 ++++-------- 5 files changed, 18 insertions(+), 20 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5388f692..964b07ce 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -124,4 +124,3 @@ jobs: secrets: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} - PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 9421b5ed..b4db110a 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -6,9 +6,6 @@ on: destination_dir: required: true type: string - secrets: - PUBLISH_DOCS_TOKEN: - required: true jobs: publish-docs-to-gh-pages: @@ -16,11 +13,19 @@ jobs: runs-on: ubuntu-latest environment: github-pages permissions: - contents: write + contents: read + id-token: write steps: - name: Ensure `destination_dir` is not empty if: ${{ inputs.destination_dir == '' }} run: exit 1 + - name: Get access token + id: get-token + uses: MetaMask/github-tools/.github/actions/get-token@v1 + with: + token-exchange-url: ${{ vars.TOKEN_EXCHANGE_URL }} + permissions: | + contents: write - name: Checkout and setup environment uses: MetaMask/action-checkout-and-setup@v3 with: @@ -31,6 +36,6 @@ jobs: - name: Deploy to `${{ inputs.destination_dir }}` directory of `gh-pages` branch uses: peaceiris/actions-gh-pages@de7ea6f8efb354206b205ef54722213d99067935 with: - personal_token: ${{ secrets.PUBLISH_DOCS_TOKEN }} + personal_token: ${{ steps.get-token.outputs.token }} publish_dir: ./docs destination_dir: ${{ inputs.destination_dir }} diff --git a/.github/workflows/publish-main-docs.yml b/.github/workflows/publish-main-docs.yml index b9bbbefc..89d10e1e 100644 --- a/.github/workflows/publish-main-docs.yml +++ b/.github/workflows/publish-main-docs.yml @@ -8,9 +8,8 @@ jobs: publish-to-gh-pages: name: Publish docs to `staging` directory of `gh-pages` branch permissions: - contents: write + contents: read + id-token: write uses: ./.github/workflows/publish-docs.yml with: destination_dir: staging - secrets: - PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} diff --git a/.github/workflows/publish-rc-docs.yml b/.github/workflows/publish-rc-docs.yml index dc8573d2..71967b94 100644 --- a/.github/workflows/publish-rc-docs.yml +++ b/.github/workflows/publish-rc-docs.yml @@ -25,10 +25,9 @@ jobs: publish-to-gh-pages: name: Publish docs to `rc-${{ needs.get-release-version.outputs.release-version }}` directory of `gh-pages` branch permissions: - contents: write + contents: read + id-token: write uses: ./.github/workflows/publish-docs.yml needs: get-release-version with: destination_dir: rc-${{ needs.get-release-version.outputs.release-version }} - secrets: - PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml index 6447a0d1..f9f27caf 100644 --- a/.github/workflows/publish-release.yml +++ b/.github/workflows/publish-release.yml @@ -7,8 +7,6 @@ on: required: false SLACK_WEBHOOK_URL: required: true - PUBLISH_DOCS_TOKEN: - required: true permissions: contents: read @@ -113,23 +111,21 @@ jobs: name: Publish docs to `${{ needs.get-release-version.outputs.RELEASE_VERSION }}` directory of `gh-pages` branch needs: get-release-version permissions: - contents: write + contents: read + id-token: write uses: ./.github/workflows/publish-docs.yml with: destination_dir: ${{ needs.get-release-version.outputs.RELEASE_VERSION }} - secrets: - PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} publish-release-to-latest-gh-pages: name: Publish docs to `latest` directory of `gh-pages` branch needs: publish-npm permissions: - contents: write + contents: read + id-token: write uses: ./.github/workflows/publish-docs.yml with: destination_dir: latest - secrets: - PUBLISH_DOCS_TOKEN: ${{ secrets.PUBLISH_DOCS_TOKEN }} publish-release: name: Publish to GitHub