Kyle Tang's blog

# 给VuePress增加自动构建并发布到github.io

# 1. 思路

github为代码库提供了 action功能（点击查看更多） (opens new window) ，在push完以后，触发一个任务脚本，可以实现持续集成的功能。

# 2. 流程描述

  1. 创建两个仓库

    我们编写的VuePress工程属于源码，发布到github.io里的是构建之后的内容。这个源码我不想公开，我们需要在github上创建两个代码库，一个是kyletang.github.io，公开访问权限，另一个是KyleTangPages私有仓库。

  2. 申请github access token

    将代码提交到KyleTangPages，触发KyleTangPages的action任务，执行自动构建并push到kyletang.github.io，因为这里要push到kyletang.github.io，这个操作是需要权限的，需要先申请一个 github access token（点击查看更多） (opens new window) ，再通过命令行或脚本push代码时，就可以使用access token来完成身份验证。

  3. 为github仓库配置环境密钥

    很显然，这个access token如果配置在action的自动任务脚本里是不合适的，因为谁有了这个，就可以访问我们github上的所有仓库了（具体都有什么权限，申请的时候可以分配）。 github允许我们将access token的值保存在KyleTangPages仓库里的 环境密钥（点击查看更多） (opens new window) 中，脚本在执行的时候，就可以从环境变量中获取access token。

  4. 给私有库增加actions脚本

    详见下文

流程示意图

示意图

# 3. 实战

了解了整体的流程，我们还需要一个把vuepress进行自动构建的脚本，vuepress官方提供的教程: 部署GitHub Pages and Github Actions (opens new window) 里提供了例子。

  1. 在个人中心里创建 github access token（点击查看帮助） (opens new window) ;
  2. 在KyleTangPages仓库下，创建一个 secrets 环境密钥（点击查看帮助） (opens new window)，填入刚创建的，名字为 ACCESS_TOKEN ,值为刚才创建的那个 token
  3. 在KyleTangPages项目的根目录下的 .github/workflows 目录（没有的话，请手动创建一个）下创建一个 .yml 或者 .yaml 文件，如:vuepress-deploy.yml; 内容如下：
name: Build and Deploy:MASTER
on: [push]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Build and Deploy
      uses: jenkey2011/vuepress-deploy@master
      env:
        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
        TARGET_REPO: KyleTang/kyletang.github.io
        TARGET_BRANCH: master
        BUILD_SCRIPT: yarn && yarn docs:build
        BUILD_DIR: docs/.vuepress/dist/
        COMMIT_MESSAGE: Auto deploy from Github Actions
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

这里说明一下

on 的意思，是在push的时候触发

jobs 里有一个任务名为build-and-deploy

runs-on 这个任务运行在 ubuntu-latest 的环境，ubuntu-latest表示最新版的ubuntu系统（docker镜像）。

这个任务分两步(step)执行, 每一步有一个action组件，uses表示使用的action组件的github库路径（用户名/仓库@分支）

env是在这行这个步骤的时候环境变量。

TARGET_REPO是 https://github.com/jenkey2011/vuepress-deploy (opens new window) 项目里entrypoint.sh里用到的环境变量，表示要发布到的github.io库的名字。

BUILD_SCRIPT是构建脚本，自己本地怎么构建，这里就怎么写。

# 4. 查看构建情况

在actions里查看 1

点击一个workflow，查看详情 2

点击左边的jobs，可以查看任务的执行过程 3

# 5. 写在后边的话

# 5.1 github.io里只能看到最后一次的提交记录，历史的都被覆盖的问题

jenkey2011/vuepress-deploy的entrypoint.sh脚本里，会通过git push -f 强制覆盖的方式push，所以，*.github.io 里只会有最新的那次提交，看不到过往的提交记录，这也没什么，因为vuepress每次都是全部构建，看这个历史提交意义不大。

如果你也和我一样有点强迫症（毕竟有问题还能方便回退），可以使用我改改过的，在上面 uses的区域，把jenkey2011/vuepress-deploy改成KyleTang/vuepress-deploy就可以了。

# 5.2 在windows上手工执行的增量提交批处理文件

脚本 deployGithubPage.cmd

rem 部署到github pages, WS是workspace的意思

set WS_BLOG=D:\gitrepo\KyleTangPages

set WS_PAGES=D:\gitrepo\kyletang.github.io

rem 拉取github pages到本地
cd /d %WS_PAGES%
git.exe pull --progress -v --no-rebase "origin"

if %errorlevel% neq 0 pause exit

rem 复制编译好的文件到pages目录
xcopy %WS_BLOG%\docs\.vuepress\dist %WS_PAGES% /Y /S /E

rem 本地提交
git add .
git commit -m "auto deploy on windows"

if %errorlevel% neq 0 pause exit

rem 推送到kyletang.github.io
git.exe push --progress "origin" master:master

if %errorlevel% neq 0 pause exit

cd ..
pause
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 5.3 github的actions有免费的额度

如果使用超了，需要付费，见这里：关于 GitHub Actions 的计费 (opens new window)

# 6. 参考资料