GitHub Actions部署GH Pages报could not read Password错误

问题表现 #

执行Deploy to GH Pages步骤时，git操作可正常识别GitHub用户名，但无法读取认证密码，抛出如下报错：

create mode 100644 static/media/flow.edad2ac1.svg
create mode 100644 static/media/plugin.d494b228.svg
create mode 100644 static/media/repo.6d496322.svg
create mode 100644 static/media/stackalt.dba9fbb3.svg
fatal: could not read Password for 'https://***@github.com': No such device or address

问题原因 #

• 所用第三方部署Actionnicoinch/ghpages@v3.0.0-alpha-1默认读取的认证凭证环境变量名为GITHUB_TOKEN，配置中传入的GH_PAT变量不会被该Action识别，导致推送时拿不到有效密码。
• 旧版actions/checkout@v2默认未开启凭证持久化，后续步骤执行git操作时无法复用工作流内置的认证信息。
• 工作流未显式配置contents写入权限，内置GITHUB_TOKEN默认没有推送分支到仓库的权限。

修复步骤 #

1. 升级checkout、setup-node、cache等官方Action到较新稳定版本，显式开启checkout步骤的凭证持久化
2. 修正部署步骤的环境变量名，传入Action可识别的GITHUB_TOKEN变量
3. 给工作流配置contents写入权限，保证token有推送分支的操作权限

修正后的完整工作流配置如下：

deployToGhPages:
  name: Deploy to GH Pages
  needs: [lint, tests]
  runs-on: ubuntu-latest
  permissions:
    contents: write
  steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        persist-credentials: true

    - name: Setup
      uses: actions/setup-node@v4
      with:
        node-version: 16

    - uses: actions/cache@v3
      id: cache
      with:
        path: |
          node_modules
          */*/node_modules
        key: ${{ secrets.CACHE_VERSION }}-${{ runner.os }}-yarn-cache-${{ hashFiles('**/yarn.lock') }}

    - name: Yarn Build
      run: yarn build
    - name: Build Storybook
      if: steps.cache.outputs.cache-hit != 'true'
      run: yarn build-storybook
    - name: Deploy to GH pages
      uses: nicoinch/ghpages@v3.0.0-alpha-1
      env:
        BUILD_DIR: storybook-static/
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

额外检查项 #

如果替换配置后仍有权限报错，到仓库Settings > Actions > General页面，找到Workflow permissions配置项，勾选Read and write permissions后保存即可。
如果不想用第三方Action，也可以直接替换为GitHub官方维护的pages部署Action组合，不会出现第三方工具的凭证兼容问题。

内容的提问来源于stack exchange，提问作者Namu