From 71a33d314b54aef1ac878fde5f8655b521038942 Mon Sep 17 00:00:00 2001 From: Huang-Ming Chang Date: Wed, 22 Apr 2026 00:29:25 +0200 Subject: [PATCH] =?UTF-8?q?ci(docs):=20drop=20self-flip=20step=20=E2=80=94?= =?UTF-8?q?=20GITHUB=5FTOKEN=20can't=20call=20Pages=20admin=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The idempotent `gh api PUT /pages -F build_type=workflow` step was meant to self-heal the Pages source from the legacy `gh-pages` branch to `workflow` on the first run. It always returns 403 because the workflow's `GITHUB_TOKEN` — even with `pages: write` declared — can only DEPLOY via Pages (the `deploy-pages` action), not modify the Pages site settings, which is a repo-admin scope. Done manually instead: `gh api -X PUT repos/$REPO/pages -F build_type=workflow` from an admin-authed CLI. Comment added describing the one-time flip so it's visible next time someone reads the workflow. First docs.yml run on master failed at this step; removing it lets the rerun complete — Pages is already in workflow mode now. --- .github/workflows/docs.yml | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 361fa026..4cfbbbd0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -28,18 +28,14 @@ jobs: steps: - uses: actions/checkout@v4 - # The repo's Pages source used to be the `gh-pages` branch - # (legacy Storybook publish). `actions/deploy-pages` requires the - # source to be `workflow`, so idempotently flip it before we do - # anything else. The PUT is a no-op once the setting is already - # `workflow` — safe to run on every deploy. - - name: Ensure Pages is configured for Actions-based deploys - working-directory: . - run: | - gh api -X PUT "repos/${{ github.repository }}/pages" \ - -F build_type=workflow - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # Pages `build_type` must be `workflow` for `actions/deploy-pages` + # to accept artifacts. That setting is flipped via the repo + # owner once (Settings → Pages → Source: GitHub Actions) or with + # `gh api -X PUT repos///pages -F build_type=workflow` + # from an admin-authed gh CLI. The workflow can't flip it itself: + # `GITHUB_TOKEN` with `pages: write` is enough to DEPLOY, but the + # Pages admin API (PUT /pages) requires repo-admin scope, which + # the workflow token doesn't carry. - uses: actions/setup-node@v4 with: