发布原理
无论使用什么CI工具发布vuepress到Github Pages,一共就三步:
CI发布工具
发布的CI工具常见的有以下几个:
Travis-ci
它一共有两个服务,分别是Travis-ci.org 和 Travis-ci.com,其中org只支持开源仓库,.com可以支持私有仓库。并且Travis-ci在规划将所有的服务并到travis-com中。 所以如果使用Travis-ci,那就直接使用Travis-ci.com这个服务吧。而且用com的服务还能授权部分仓库,也不必配置Webhooks,强迫症福音。
- 优点:
- 缺点:
- 如果要再发布到自己的服务器上,无法通过变量添加know_hosts 以避免交互输入,可参见我的Travis-ci配置。
- 电信网络访问慢,甚至 Status badge 图标都加载不出来(当然不能怪人家)
Github workflow Actions
目前不推荐,还不够成熟。应用市场里只有三方应用功能全一点,例如GitHub Pages action
和vuepress-deploy
。
- 缺点:创建任务只能在线修改和编辑yml文件,本地编辑完了推送不生效。还好本地删除再推送还好用,否则想删都删不了。
- 优点:Status badge 图标好看
Microsoft Azure pipelines
本文主角
- 优点:
- 可以高度自定义,可参见我后面的配置文件
- 安全,完全自主控制,不依赖任何三方应用
- Status badge 图标好看(又颜控了)
- 网络连通性较好,放上个
Install B
的 Status badge
图标能显示出来 - 支持Windows环境构建(虽然我用不到)
- 缺点:
- 触发器trigger不支持变量(You cannot use variables in paths, as variables are evaluated at runtime (after the trigger has fired).
- 官方task缺乏,唯一一个叫"Publish to Github Pages"的Task,还只支持windows 😂😂😂
当然,除了发布到github pages(github.io),你还可以发布到 Azure Static Web Apps。参考:Tutorial: Publish a VuePress site to Azure Static Web Apps Preview,当然,这是另一个话题,不再展开。
本文主要说的是使用Azure Pipelines 来发布Vuepress 到 Github Pages.
Azure Pipelines
开始步骤
从Github应用市场找到Azure Pipelines安装,可以参考:这里
注意第Task 1 第12步,如果只想选定特定的仓库,可以只授权部分仓库(Only select repositories)
到Task 2第4步的时候,可以使用我写的配置,代码有点多,看注释就能看懂了
Task 3,4,5就不用看了。如果想给自己的README.md添加一个 status badge 图标,看Task 6。
注意:
如果要给README.md添加图标,但Vuepress仍然需要使用一个markdown承载首页的Frontmatter,你可以创建一个index.md用来写Frontmatter,否则如果写在README.md中,会在Vuepress渲染首页时加载到页面里。
当然,也可以从Azure 开始,选择Start free with GitHub 或者用你的微软帐户登录Azure,选择Pipelines,然后创建组织,创建项目,关联Github. 入口多种多样。
配置文件
配置文件说明:
文件名和路径:放在项目根目录下,命名为azure-pipelines.yml
配置项的几个变量,要去Azure Pipelines的编辑界面,点右侧的Variables铵钮设置添加,然后要点保存。
GITHUB_TOKEN: 是必须的,并且一定要选加密,谁也不希望自己Github的密钥泄漏出去吧。
BUILD_SCRIPT:默认是yarn docs:build
,如果你的package.json中还配置了其它的,可以设置它
CNAME:用于你配置了Github Pages的独立域名时,在根目录生成一个写着域名的CNAME文件,当然你把它放在.vuepress/public
目录下效果也是一样的。
TARGET_BRANCH:要发布的分支,如果是 username.github.io,要选master
分支,如果是https://<USERNAME>.github.io/<REPO>
,则是gh-pages
分支,默认是gh-pages
分支
代码不用动,只需要配置1到2个变量就行了。然后再次提交并推送你的主分支,就会触发Azure Pipelines 的 build和deploy。
GITHUB_TOKEN一定要选加密! GITHUB_TOKEN一定要选加密! GITHUB_TOKEN一定要选加密!
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
| # Node.js with Vue
# Build a Node.js project that uses Vue.
# Add steps that analyze code, save build artifacts, deploy, and more:
# https://docs.microsoft.com/azure/devops/pipelines/languages/javascript
#
# You can set Variables on pipelines web console.
# @see https://docs.microsoft.com/zh-cn/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables
#
# Variables list:
# variables name Required Keep secret Default value Example
# GITHUB_TOKEN yes yes
# BUILD_SCRIPT no no yarn docs:build
# CNAME no no www.youdomain.com
# TARGET_BRANCH no no gh-pages master
#
# GITHUB_TOKEN generate from: https://github.com/settings/tokens
# @see https://docs.microsoft.com/zh-cn/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#ci-triggers
trigger:
branches:
include:
- '*' # must quote since "*" is a YAML reserved character; we want a string, you can use: {master} or {your branch name}
pool:
vmImage: 'ubuntu-latest'
steps:
- task: NodeTool@0
inputs:
# 注意设置版本号,选12.x,默认是10.x,非常坑
versionSpec: '12.x'
displayName: 'Install Node.js'
- bash: |
yarn install --registry https://registry.yarnpkg.com --no-lockfile
mkdir -p /tmp/dist
# For not secret variables,use $variablesname or ${variablesname}
# For secret variables, use $(variablesname)
if [[ -z "${BUILD_SCRIPT}" ]]; then
script="yarn docs:build -d /tmp/dist"
else
script="${BUILD_SCRIPT} -d /tmp/dist"
fi
echo "Start building:"$script
eval $script
# set variable: build_dir
# @see https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops
echo "##vso[task.setvariable variable=build_path]/tmp/dist"
displayName: 'yarn install and build'
- bash: |
if [ "$CNAME" ]; then
echo "Generating a CNAME file..."
echo $CNAME > CNAME
fi
workingDirectory: $(build_path)
displayName: 'Generate a CNAME file'
- script: |
# use $(Build.Repository.ID) or ${BUILD_REPOSITORY_ID}
DEPLOY_REPO="https://$(GITHUB_TOKEN)@github.com/$(Build.Repository.ID).git"
if [[ -z "$TARGET_BRANCH" ]]; then
DEPLOY_BRANCH="gh-pages"
else
DEPLOY_BRANCH="$TARGET_BRANCH"
fi
if [[ -z "$(GITHUB_TOKEN)" ]]; then
echo "ERROR: github token is not valid"
exit 0
else
echo "github token is valid"
fi
git init
git config user.name "Azure pipelines"
git config user.email "pipelines@users.noreply.github.com"
git add --all;
git commit -m"Pipelines-Bot: Auto deploy via $(Build.SourceVersion)";
git push --force $DEPLOY_REPO master:$DEPLOY_BRANCH
workingDirectory: $(build_path)
displayName: '[Git] Commit and push to Github Pages branch'
|
查看任务过程和结果
点击项目左侧的Pipelines菜单,右侧的 Recently run pipelines 是Pipelines配置文件维度。再点进去才是历次的执行结果。看每一步的执行情况,多点几次就进去了。
发布到自己的服务器
如果要发布到自己的服务器,可以使用rsync、ssh scp等几种方式。我这里偷懒不配rsync,就简单使用scp了。
上传私钥
需要将ssh的rsa私钥上传到Pipelines管理界面的Library里,参考 这里。所以最好给发布站点单独建一套用户和公私钥,不要用root的私钥。
- In Azure Pipelines, select the Library tab.
- Select the Secure files tab at the top.
- Select the secure file you want to authorize.
- In the details view under Properties, select Authorize for use in all pipelines, and then select Save.
增加配置
然后增加azure-pipelines.yml配置如下:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| # 安装私钥任务
- task: InstallSSHKey@0
inputs:
# Set "HOST_ADDR" Viriables on pipelines edit web interface
knownHostsEntry: '$(HOST_ADDR)'
# @see https://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops
# upload your ssh private key on pipelines "Labrary"
sshKeySecureFile: 'deploy_rsa' # 上传的文件名
displayName: 'install ssh key.'
# 发布站点脚本
- bash: |
# Set HOST_PORT,HOST_USER,HOST_ADDR and HOST_DEPLOY_PATH Viriables on the pipelines edit web interface
scp -P $(HOST_PORT) -o StrictHostKeyChecking=no -r $(build_path)/* $(HOST_USER)@$(HOST_ADDR):$(HOST_DEPLOY_PATH)
displayName: 'Push to Hosts server.'
|
授予权限
在Pipelines的Recent 标签页中,进入Runs列表,点击查看状态会有授权的提示,授权Pipelines访问你的 Secure files。
调试工具
参考azure-cli工具的 az pipelines 先挖个坑,还没用明白,对于没有使用付费服务的来说,看样子用处不大。