Github-Actions自动部署gh-pages

简介

本文以vuepress-theme-hope项目为例，介绍使用Github-Actions将网站自动部署到gh-pages分支的方法。 gh-pages分支的方法。

概念说明

GitHub Actions

官方文档：https://docs.github.com/zh/actions/learn-github-actions/understanding-github-actions

GitHub Actions 是 GitHub 平台提供的一项持续集成/持续部署（CI/CD）服务。它可以帮助开发人员自动化代码构建、测试和部署，以提高开发效率和代码质量。GitHub Actions 可以在 GitHub 上的代码仓库中配置和运行，也可以在自己的服务器上运行。

使用 GitHub Actions，您可以创建一个由事件驱动的工作流程，该工作流程将在您的代码库中的某些事件发生时自动触发，例如推送代码、创建分支或发布新版本。工作流程由一个或多个步骤组成，每个步骤都可以执行特定的操作，例如运行测试、构建代码或部署应用程序。GitHub Actions 支持多种编程语言和工具，例如 Node.js、Python、Java、Docker 等等。

GitHub Actions 提供了一些内置的 Action（动作），这些 Action 可以用来执行常见的任务，例如编译代码、运行测试、部署应用程序等等。您也可以创建自己的 Action，并将其发布到 GitHub Marketplace 上供其他开发人员使用。

总之，GitHub Actions 是一个强大的自动化工具，可以帮助开发人员轻松地集成测试、构建和部署流程，并提高生产力和代码质量。

gh-pages

gh-pages 是 GitHub Pages 功能默认使用的一个仓库代码分支，GitHub Pages是一种静态站点托管服务，由 GitHub 提供。使用 gh-pages，您可以将自己的静态网站部署到 GitHub 平台上，并通过网址进行访问。（PS：使用 GitHub Pages 需要手动开启）

当您在 GitHub 上创建一个公共仓库时，如果您在该仓库中创建一个名为 gh-pages 的分支，并将您的静态网站文件（例如 HTML、CSS、JavaScript 文件）推送到该分支中，则您的网站将被自动部署到 GitHub Pages 上。一旦部署完成，您可以通过 username.github.io/repository-name 这样的网址进行访问。

除了使用 gh-pages 分支外，GitHub Pages 还支持使用 /docs 目录作为托管静态站点的源。在这种情况下，您只需将您的静态站点文件放置在 /docs 目录中，然后将其推送到 master 分支中即可。

总之，gh-pages 是一种方便的静态站点托管服务，可以帮助开发人员轻松地将自己的网站部署到 GitHub 平台上，并与其他开发者和用户共享。

操作步骤

要将 GitHub 仓库代码使用 GitHub Actions 自动部署到 gh-pages 分支，具体步骤如下：

在 GitHub 仓库中创建一个名为 .github/workflows/deploy.yml 的文件，并在其中编写自动化工作流程的配置。
在 deploy.yml 文件中，使用 JamesIves/github-pages-deploy-action Action，该 Action 可以帮助您将您的站点构建输出（例如，VuePress 的 dist 目录）推送到 gh-pages 分支上。
在 GitHub 仓库中创建一个 Secret，用于授权 Action 访问您的仓库。该 Secret 是 GitHub 平台自动生成的一个 Access Token。

deploy.yml配置文件用于配置一个工作流程，将在将代码推送到 main 分支时触发，工作流程包含了以下几个步骤：

检出代码仓库；

安装依赖；

构建 VuePress 站点；

使用 JamesIves/github-pages-deploy-action 将构建输出推送到 gh-pages 分支上。

这个工作流程需要使用 Secret 授权 Action 访问您的仓库。请确保在 GitHub 仓库的 "Settings" 页面中添加该 Secret，以便工作流程能够成功运行。

注意，当您将工作流程文件推送到 GitHub 仓库时，GitHub Actions 将自动运行工作流程。您也可以手动触发工作流程，例如通过在仓库页面中点击 "Actions" 选项卡，然后选择 "Deploy" 工作流程并点击 "Run workflow" 按钮。

实例操作

基本流程

本实例使用vuepress-theme-hope初始化创建项目。

创建本地项目（参考vuepress-theme-hope官方文档，选择docs类型项目）;
创建github仓库；
开启github仓库的Github Pages功能（自行研究）；
提交本地项目源码到Github仓库。

项目自动生成后，根目录下会生成.github/workflows/deploy-docs.yml配置文件，在.github/workflows文件夹下的所有yml文件都会被视为GitHub Actions的配置文件。初始配置文件内容如下：

yaml
name: 部署文档

on:
  push:
    branches:
      # 确保这是你正在使用的分支名称
      - main

jobs:
  deploy-gh-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          # 如果你文档需要 Git 子模块，取消注释下一行
          # submodules: true

      - name: 设置 Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: yarn

      - name: 安装依赖
        run: yarn install --frozen-lockfile

      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: |-
          yarn run docs:build
          > src/.vuepress/dist/.nojekyll

      - name: 部署文档
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: src/.vuepress/dist

额外需要

在基本流程中，提交本地项目源码到Github仓库时，会触发Github Actions，在Github项目的Actions页面可以看到任务执行情况。

使用基本流程中的默认配置，在我测试的时候会报错：


/usr/bin/git push --force ***github.com/DingDangDog/docs-test.git github-pages-deploy-action/bgupwwhtr:gh-pages
remote: Permission to DingDangDog/docs-test.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/DingDangDog/docs-test.git/': The requested URL returned error: 403
Running post deployment cleanup jobs… 🗑️
/usr/bin/git checkout -B github-pages-deploy-action/bgupwwhtr
Reset branch 'github-pages-deploy-action/bgupwwhtr'
/usr/bin/chmod -R +rw github-pages-deploy-action-temp-deployment-folder
/usr/bin/git worktree remove github-pages-deploy-action-temp-deployment-folder --force
Error: The deploy step encountered an error: The process '/usr/bin/git' failed with exit code 128 ❌
Notice: Deployment failed! ❌

经过学习了解，大概是因为自动部署时，没有仓库权限，导致报错并部署失败，解决该问题有两种方式：

官方说明：If you do not supply the action with an access token or an SSH key, you must access your repositories settings and provide Read and Write Permissions to the provided GITHUB_TOKEN, otherwise you'll potentially run into permission issues. Alternatively you can set the following in your workflow file to grant the action the permissions it needs.

通过permissions配置提权
通过配置Token赋权

详细了解可于都JamesIves/github-pages-deploy-action项目文档：README

以上两种方式都需要修改deploy-docs.yml，修改后重新提交代码到Github仓库即可，Github Actions会自动重新运行脚本部署。

permissions配置提权

在deploy-docs.yml文件中，增加以下配置，用户获取仓库写权限。

yml
permissions:
  contents: write

配置TOKEN

配置TOKEN主要分为以下三步；

生成github-token

在Github账户设置中，依次找到Developer settings>Personal access tokens>Tokens (classic)，点击Generate new token (classic)，并勾选相应权限，主要有：repo、workflow两大权限。

重要：点击生成后，将Token内容保存好，因为Token内容只能在此时可见，如果丢失只能重新生成。

在仓库配置Secrets中增加Token

打开仓库的Setting页面，找到Secrets and variables>Actions，点击New repository secret创建Secret，其中Name自定义即可，尽量见名知意，如ACCESS_TOKEN表示授权，Secret填入上一步创建的Token。

在workflow配置中增加token配置

如下配置部分内容，增加其中token: ${{ secrets.ACCESS_TOKEN }}配置，表示从仓库的secrets中获取ACCESS_TOKEN。

yml
      - name: 部署文档
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # 这是文档部署到的分支名称
          token: ${{ secrets.ACCESS_TOKEN }}
          branch: gh-pages
          folder: src/.vuepress/dist

拓展

GitHub Actions 中使用的 secret 名称没有固定的要求，您可以根据自己的需要为它们命名。不过，为了方便起见，建议将 secret 命名为与其功能相关的名称，例如：

ACCESS_TOKEN：用于身份验证的访问令牌。
API_KEY：用于访问某个 API 的 API 密钥。
SSH_PRIVATE_KEY：用于 SSH 连接的私钥。
DOCKER_USERNAME 和 DOCKER_PASSWORD：用于 Docker Hub 认证的用户名和密码。
GITHUB_TOKEN：用于访问 GitHub API 的 OAuth2 token。
SLACK_WEBHOOK_URL：用于将消息发送到 Slack 的 webhook URL。

请注意，在为 secret 命名时，请确保不要包含任何敏感信息或密码，因为 secret 值是加密的，但名称是公开的。