JetBrains Writerside部署至GitHub Pages遇错误求助

问题场景 #

在私有仓库维护Writerside文档及相关内容，尝试通过Docker部署方式发布到公开的GitHub Pages仓库时，执行Actions的Setup Pages步骤（使用actions/configure-pages@v3）出现报错。

报错信息 #

Error: Get Pages site failed. Please verify that the repository has Pages enabled and configured to build using GitHub Actions, or consider exploring the enablement parameter for this action.

Error: HttpError: Not Found

当前使用的yml配置文件 #

name: writeside build

on:
# If specified, the workflow will be triggered automatically once you push to the `main` branch.
# Replace `main` with your branch’s name
push:
branches: ["master"]
# Specify to run a workflow manually from the Actions tab on GitHub
#workflow_dispatch:

# Gives the workflow permissions to clone the repo and create a page deployment
permissions:
contents: read
id-token: write
pages: write

env:
# Name of module and id separated by a slash
INSTANCE: Writerside/hi
# Replace HI with the ID of the instance in capital letters
ARTIFACT: webHelpHI2-all.zip
# Writerside docker image version
DOCKER_VERSION: 232.10275
# Add the variable below to upload Algolia indexes
# Replace HI with the ID of the instance in capital letters
ALGOLIA_ARTIFACT: algolia-indexes-HI.zip
ALGOLIA_APP_NAME: xxxxxx
ALGOLIA_INDEX_NAME: xxx
ALGOLIA_KEY: ${{ secrets.ALGOLIA_KEY }}
CONFIG_JSON_PRODUCT: HI
CONFIG_JSON_VERSION: 1.0

jobs:
build:
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v3

- name: Build Writerside docs using Docker
uses: JetBrains/writerside-github-action@v4
with:
instance: ${{ env.INSTANCE }}
artifact: ${{ env.ARTIFACT }}
docker-version: ${{ env.DOCKER_VERSION }}

- name: Upload documentation
uses: actions/upload-artifact@v3
with:
name: docs
path: |
artifacts/${{ env.ARTIFACT }}
artifacts/report.json
retention-days: 7

# Add the step below to upload Algolia indexes
- name: Upload algolia-indexes
uses: actions/upload-artifact@v3
with:
name: algolia-indexes
path: artifacts/${{ env.ALGOLIA_ARTIFACT }}
retention-days: 7

# Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when  documentation contains errors
test:
# Requires build job results
needs: build
runs-on: ubuntu-latest

steps:
- name: Download artifacts
uses: actions/download-artifact@v1
with:
name: docs
path: artifacts

- name: Test documentation
uses: JetBrains/writerside-checker-action@v1
with:
instance: ${{ env.INSTANCE }}

publish-indexes:
# Requires the build-job results
needs: build
runs-on: ubuntu-latest
container:
Image: registry. Jetbrains. Team/p/writerside/builder/algolia - publisher: 2.0.32-2

steps:
- name: Download artifact
uses: actions/download-artifact@v3
with:
name: algolia-indexes
- name: Unzip artifact
run: |
unzip -O UTF-8 -qq ${{ env.ALGOLIA_ARTIFACT }} -d algolia-indexes
env "algolia-key=${{env.ALGOLIA_KEY}}" java -jar /opt/builder/help-publication-agent.jar \
update-index \
--application-name ${{env.ALGOLIA_APP_NAME}} \
--index-name ${{env.ALGOLIA_INDEX_NAME}} \
--product ${{env.CONFIG_JSON_PRODUCT}} \
--version ${{env.CONFIG_JSON_VERSION}} \
--index-directory algolia-indexes/ \
2>&1 | tee algolia-update-index-log.txt

deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
# Requires the build job results
needs: test
runs-on: ubuntu-latest
steps:
- name: Download artifact
uses: actions/download-artifact@v3
with:
name: docs

- name: Unzip artifact
run: unzip -O UTF-8 -qq ${{ env.ARTIFACT }} -d dir

- name: Setup Pages
uses: actions/configure-pages@v3

- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: dir

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1

解决方案 #

1. 配置目标Pages仓库的部署源 #

打开你的公开GitHub Pages仓库，进入Settings > Pages，在Build and deployment区域将Source设置为GitHub Actions，保存设置。

2. 更新私有仓库的Actions权限 #

在yml的permissions部分添加contents: write，确保有跨仓库写入权限：

permissions:
  contents: write
  id-token: write
  pages: write

3. 替换部署逻辑，推送产物到目标仓库 #

删除原deploy job中的Setup Pages、Upload artifact、Deploy to GitHub Pages步骤，替换为以下内容，将构建好的静态文件推送到目标Pages仓库的gh-pages分支：

deploy:
  environment:
    name: github-pages
    url: https://<你的GitHub用户名>.github.io/<Pages仓库名称>/
  needs: test
  runs-on: ubuntu-latest
  steps:
    - name: Download artifact
      uses: actions/download-artifact@v3
      with:
        name: docs

    - name: Unzip artifact
      run: unzip -O UTF-8 -qq ${{ env.ARTIFACT }} -d dir

    - name: Push to Pages repository
      uses: peaceiris/actions-gh-pages@v3
      with:
        personal_token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
        external_repository: <你的GitHub用户名>/<Pages仓库名称>
        publish_dir: ./dir
        publish_branch: gh-pages

• 需在私有仓库的Settings > Secrets and variables > Actions中添加PAGES_DEPLOY_TOKEN：在GitHub个人设置中生成Fine-grained token，权限选择Contents: Write，并确保该token有目标Pages仓库的访问权限。

4. 修复配置中的格式错误 #

原publish-indexes job里的container地址存在空格，修正为：

container:
  image: registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-2

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