Github-Actions自动部署gh-pages

## 简介

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

<!-- more -->

## 概念说明

### GitHub Actions

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

<!-- 文章内嵌广告位 -->
<div class="article-ads"></div>

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 分支，具体步骤如下：

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

<!-- 文章内嵌广告位 -->
<div class="article-ads"></div>

> deploy.yml配置文件用于配置一个工作流程，将在将代码推送到 main 分支时触发，工作流程包含了以下几个步骤：
> 1. 检出代码仓库；
> 2. 安装依赖；
> 3. 构建 VuePress 站点；
> 4. 使用 JamesIves/github-pages-deploy-action 将构建输出推送到 gh-pages 分支上。
> 
> **这个工作流程需要使用 Secret 授权 Action 访问您的仓库。请确保在 GitHub 仓库的 "Settings" 页面中添加该 Secret，以便工作流程能够成功运行。**

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

## 实例操作

### 基本流程

> 本实例使用[vuepress-theme-hope](https://theme-hope.vuejs.press/zh/)初始化创建项目。

1. 创建本地项目（`参考vuepress-theme-hope官方文档，选择docs类型项目`）;
2. 创建github仓库；
3. 开启github仓库的Github Pages功能（自行研究）；
4. 提交本地项目源码到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
```

<!-- 文章内嵌广告位 -->
<div class="article-ads"></div>

### 额外需要

在基本流程中，提交本地项目源码到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.

1. 通过`permissions`配置提权
2. 通过配置`Token`赋权

详细了解可于都`JamesIves/github-pages-deploy-action`项目文档：[README](https://github.com/JamesIves/github-pages-deploy-action#readme)

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

<!-- 文章内嵌广告位 -->
<div class="article-ads"></div>

#### permissions配置提权

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

```yml
permissions:
  contents: write
```

#### 配置TOKEN

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

1. 生成github-token

> 在Github账户设置中，依次找到`Developer settings`>`Personal access tokens`>`Tokens (classic)`，点击`Generate new token (classic)`，并勾选相应权限，主要有：`repo`、`workflow`两大权限。
> 
> **重要：点击生成后，将Token内容保存好，因为Token内容只能在此时可见，如果丢失只能重新生成。**

2. 在仓库配置Secrets中增加Token

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

3. 在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
```

<!-- 文章内嵌广告位 -->
<div class="article-ads"></div>

### 拓展

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 值是加密的，但名称是公开的。