【Gitlab】GitBook+GitLab撰写发布技术文档-Part2:GitLab篇

上一篇文章介绍了如果用 gitbook 写书，并且我们已经通过 gitbook build命令把书的内容打包成 HTML 格式发布到了_book文件夹中。
接下来这篇文章将向大家介绍如何把写好的书发布到 gitlab 上。这里 gitlab 是我们自己搭建在公司内网中的，不过要用到的原理其实都是一样的，就是利用其 CI/CD 功能。
关于 CI/CD 网上有很多详细的介绍，这里我就不不再重复啰嗦，如果有想学习的可以参看文末的致谢&引用部分。

原理

简单来说CI 就类似一个触发器，你可以设定响应触发的条件，比如 master 分支有新的 commit合并进来，或者带有特殊 tag 的合并，亦或者其他指定分支的特殊提交，可以触发指定的指令。
一般来说标准的流程是3步，打包(build)、测试(test)和发布(deploy)。也就是我们只需要把源码提交上以后，CI 可以帮我们完成自动化部署工作。
考虑到我们在用 gitbook 写书的过程中需要预览时，其实已经在做build 和 test 的工作了，所以我们只需要在代码传到 gitlab 上后，让服务器帮我们执行发布的工作。
所以前提是我们搭建好了一个web 服务，然后 CI 帮我们把打包好的内容部署到相应的网站目录中就好了。

实现

我们就按照原理，来一步一步尝试着完成工作吧。

CI配置

还记得我们上一篇文章中最后介绍目录结构时，有提到一个文件： gitlab-ci.yml。这个文件是用YAML 进行配置，我们来看一下我们要用到的配置文件吧

deploy:
  stage: deploy
  script:
    # make backup
    - sudo rm -rf /usr/share/nginx/html/TechDocs/example_bak
    - sudo mv /usr/share/nginx/html/TechDocs/example /usr/share/nginx/html/TechDocs/example_bak
    - sudo mkdir /usr/share/nginx/html/TechDocs/example
    # deploy latest files
    - cd _book
    - sudo cp -rf . /usr/share/nginx/html/TechDocs/example/
  only:
    - master # this job will affect only the 'master' branch

这段 yaml 配置就只有deploy 的步骤，我们在 script部分进行了一系列的操作，完成旧文件的备份以及新文件的部署。当我们的代码上传到远端后，就会自动执行 script 里的内容了。让我们尝试下吧。

查看 CI 任务执行状态

上传代码到 gitlab 的步骤这里就不介绍了。理论上说，当代码上传到 master 分支后，会自动执行我们设定好的部署任务。我们可以通过访问gitlab对应项目的页面，在左侧菜单栏点击CI/CD来查看任务的执行情况。
但是如果你和我一样是第一次处理 CI 任务，我们会得到下面的提示：

原因页面上也给出了我们提示This job is waiting to be picked by a runner。

Runner

这里就需要引入第2个概念： runner。很容易从字面上理解，runner 就是我们任务的执行者，也很形象，我们提交了一个任务以后，总得有人来执行。这些任务有些是需要shell 脚本执行，有些可能需要登录到远程机器，有些可能需要 docker 的执行权限，所以这些执行者也都有个子的分工，可能有些执行者只负责执行特定项目的任务，有些执行者执行特殊 tag 的。所以接下来我们看看如何才能创建 runner 吧。

shared runner

前文提到了我们可能需要一些高权限的 runner 来跨项目间来执行任务。因为我们要做的是多个项目的技术文档，所以会有多个 gitbook 的项目，那这些项目的 CI 任务自然是公用1个 runner 就好，这种 runner 就叫做 shared runner。
shared runner 的创建需要我们用管理员的帐号登录gitlab 页面，在 admin area 区域，点击 runner 来根据提示创建。

这个页面会显示当前所有的 runner，包括项目独享的 runner 和共享的 shared runner。我们看到目前还没有一个可用的 runner，所以之前的任务才会停留在等待 runner 来运行的状态。
我们就根据页面的提示来创建 runner 吧。

安装 gitlab-runner 工具

第一步是安装工具，可以通过页面上的提示来进行不同主机环境的安装。我们这里用到的是 RHEL/CentOS，其他版本可以参见页面链接。
我们登录到自建 gitlab 所在的主机，然后执行以下脚本

$ sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
$ sudo chmod +x /usr/local/bin/gitlab-runner
$ sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
$ sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
$ sudo gitlab-runner start

新建 shared runner

工具安装好了之后，我们就可以来创建用户了。

$ gitlab-runner register

之后按照提示，一步一步创建就好了：

输入URL
输入token。 URL 和 token 按照页面上给出的提示来创建就好了。token 用来标识创建的 runner 是某个项目特有的，还是 shared runner
输入 runner 的描述，这个可以随便填写，只要自己能看明白，能区分就好了
输入特定的 tag。注意，这里最好留空，否则该 runner 仅会执行特定 tag 的提交
选择执行类型。这里提供了很多常见的执行类型，例如 docker, docker-ssh, shell 等，我们这里输入 shell。

之后我们就创建好了一个可以执行 shell 命令的 shared runner。再次回到之前的 web 页面上查看我们创建的 runner 信息。

可以看到页面提示我们已经创建了一个 runner 可以执行all unassigned projects的任务

我们还可以进入到特定的项目，在设置里面查看 runner 的情况，可以看到已经有一个可用的 shared runner。如果想创建该项目特有的 runner，按照页面上的提示，输入特定的 token 就好了。

其他细节

我们重新查看CI任务页面，大多数情况下，你的任务状态会是failed或者pendding。如果是 failed，我们可以点击查看具体失败的原因，例如我遇到的问题就是 gitlab-runner 用户没有 sudo 权限。
如果是 pendding，通常情况下是你的 job 没有合适的 runner 来执行，例如指定了分支或者添加了 tag 导致没有 runner 可用。

如果一切都设置妥当，我们可以看到 CI 页面任务的最终状态是 passed，也就是成功执行了。这样，gitbook 的内容就成功部署到你的 web 页面上了。