Gitlab-ci:從零開始的前端自動化部署

「一個Pipleline有若干個stage,每個stage上有至少一個Job」，如下圖所示：

「2.Runner」

Runner可以理解為：「在特定機器上」根據(jù)項目的**.gitlab-ci.yml「文件，對項目執(zhí)行pipeline的」程序**。Runner可以分為兩種：「Specific Runner」 和 「Shared Runner」

• 「Shared Runner」是Gitlab平臺提供的免費使用的runner程序，它由Google云平臺提供支持，每個開發(fā)團隊有十幾個。對于公共開源項目是免費使用的，如果是私人項目則有每月2000分鐘的CI時間上限。
• 「Specific Runner」是我們自定義的，在自己選擇的機器上運行的runner程序，gitlab給我們提供了一個叫g(shù)itlab-runner的命令行軟件，只要在對應(yīng)機器上下載安裝這個軟件，并且運行g(shù)itlab-runner register命令，然后輸入從gitlab-ci交互界面獲取的token進行注冊, 就可以在自己的機器上遠程運行pipeline程序了。

?

Gitlab-runner下載鏈接：https://docs.gitlab.com/runner/install/

?

「Shared Runner 和 Specific Runner的區(qū)別」

1. Shared Runner是所有項目都可以使用的，而Specific Runner只能針對特定項目運行
2. Shared Runner默認基于docker運行，沒有提前裝配的執(zhí)行pipeline的環(huán)境，例如node等。而Specific Runner你可以自由選擇平臺，可以是各種類型的機器，如Linux/Windows等，并在上面裝配必需的運行環(huán)境，當然也可以選擇Docker/K8s等
3. 私人項目使用Shared Runner受運行時間的限制，而Specific Runner的使用則是完全自由的。

「3.Executor」

什么是Executor？我們上面說過 Specific Runner是在我們自己選擇的平臺上執(zhí)行的，這個平臺就是我們現(xiàn)在說到的“Executor”，我們在特定機器上通過gitlab-runner這個命令行軟件注冊runner的時候，命令行就會提示我們輸入相應(yīng)的平臺類型?？晒┻x擇的平臺一共有如下幾種，下面是一張它們各方面特點的比較表格

下面是表格的原文鏈接

?

參考鏈接：https://docs.gitlab.com/runner/executors/#selecting-the-executor

?

「為了簡單起見，我下面的實踐部分使用的是我自己的本地Mac機器作為Executor，并且在注冊時選擇“Shell”作為Executor類型。」

「2.2 YML文件的基本語法規(guī)則」

CI流程的運行控制，決定于項目根目錄下編寫的配置文件—— 「.gitlab-ci.yml」，正因如此，我們需要掌握YML的基本語法規(guī)則。

YML是一種編寫配置文件的語言，比JSON更為簡潔和方便，因此，我們首先要掌握的就是YML文件的編寫語法。

一份簡單的YML文件長下面這個樣子：

install-job: # 注釋
  tags:
    - sss
  stage: install
  script:
    - npm install

從這里我們就可以看出：

• YML通過縮進組織層級
• YML里允許通過#符號編寫注釋

在基本結(jié)構(gòu)上，YML和 JSON也類似

• JSON是由對象，數(shù)組，以及對象和數(shù)組的嵌套結(jié)構(gòu)組成的
• YML也是由對象，數(shù)組，以及對象和數(shù)組的嵌套結(jié)構(gòu)組成的。

如下所示：

「YML中的數(shù)組寫法」

colors
  - red
  - blue
  - yellow

相當于JSON中的

{ "colors": ["red","blue","yellow"] }

「YML中的對象寫法：」

people:
  name: zhangsan
  age: 14

相當于JSON中的

{
  "people": {
     "name": "zhangsan"
     "age": 14
  } 
}

當然也可以是數(shù)組和對象之間形成的嵌套結(jié)構(gòu)

a:
  b:
    - d
  c: e

相當于

{
  "a": {
    "b": [ "d" ],
    "c": "e"
   }
}

「從JSON到Y(jié)ML之間的過渡學(xué)習(xí)的注意要點：」

• 你不再需要“{}”這種符號去區(qū)分層級邊界了，你需要考慮使用縮進
• 這里可以使用注釋，用#符號
• 如果不涉及特殊符號比如“[”，你一般是不需要給YML中的字符串加雙引號或者單引號的（當然加了也可以）

了解了這些，對于編寫一個gitlab-ci的「hello world」已經(jīng)沒有問題了。

當然YML還有著比JSON更為豐富的功能，比如用”&"符號和"<<:*”符號可以實現(xiàn)的片段導(dǎo)入的功能，以及gitlab-ci提供的include關(guān)鍵字和extend關(guān)鍵字等提供的結(jié)構(gòu)編排功能。這些我將在最后面的小節(jié)中講解，這里暫時不多贅述

2.3 gitlab-ci.yml配置的特定關(guān)鍵字

在了解了YML文件的語法格式后，接下來需要了解的就是gitlab-ci獨特的配置關(guān)鍵字，這些關(guān)鍵字將在.gitlab-ci.yml中使用，并用來控制一個pipeline具體的運作過程

gitlab提供了很多配置關(guān)鍵字，其中最基礎(chǔ)和常用的有這么幾個

• stages
• stage
• script
• tags

「stages & stage」

stages定義在YML文件的最外層，它的值是一個數(shù)組，用于定義一個pipeline不同的流程節(jié)點

例如我們定義如下:

stages: # 分段
  - install
  - eslint
  - build
  - deploy

則在Gitlab交互界面中能夠看到如下展示

我們上面說過：「Job是pipeline的任務(wù)節(jié)點，它構(gòu)成了pipeline的基本單元」

而stage/script/tags這三個關(guān)鍵字，都是作為Job的子屬性來使用的,如下所示，install就是我們定義的一個Job

install:
  tags:
    - sss
  stage: install
  script:
    - npm install

「stage」

是一個字符串，且是stages數(shù)組的一個子項，表示的是當前的pipeline節(jié)點。

當前stage的執(zhí)行情況能在交互面板上能看的清清楚楚：

• 正在執(zhí)行是藍色
• 尚未執(zhí)行是灰色
• 執(zhí)行成功是綠色
• 執(zhí)行失敗是紅色

「script」

它是當前pipeline節(jié)點運行的shell腳本（以項目根目錄為上下文執(zhí)行）。

這個script是我們控制CI流程的核心，我們所有的工作：從安裝，編譯到部署都是通過script中定義的shell腳本來完成的。

如果腳本執(zhí)行成功，pipeline就會進入下一個Job節(jié)點，如果執(zhí)行失敗那么pipeline就會終止

「tags」

tags是當前Job的標記，「這個tags關(guān)鍵字是很重要，因為gitlab的runner會通過tags去判斷能否執(zhí)行當前這個Job」

例如我們在gitlab的面板中能看到當前激活的runner的信息

Gitlab項目首頁=> setting => CI/CD => Runners

上面的這個sss就是當前Runner的tags，這意味著：**這個runner只會執(zhí)行tag為sss的Job。**如果一個Job沒有tag或者tag不是sss,那么即使這個Runner是激活且空閑的，也不會去執(zhí)行！

基本的gitlab-ci關(guān)鍵字就介紹結(jié)束了，有了這些知識對于編寫一個gitlab-ci的”hello world”已經(jīng)足夠了。對于更多的關(guān)鍵字的相關(guān)知識，將在文章最后再進行介紹

三.gitlab-ci實戰(zhàn)

「3.1 編寫一個gitlab-ci的"hello world"」

好，說了這么多終于到了實踐的部分了，請原諒前面的啰嗦，下面我將會展示一下如何從零開始實踐一個gitlab-ci的Hello world:

「1.在平臺上下載并安裝Gitlab-runner命令行」

我是在Mac上跑的ci，所以下面的適用于OSX系統(tǒng)（如果是其他平臺，可自行參考以下官方鏈接中的相關(guān)資料）

?

參考資料：https://docs.gitlab.com/runner/install/

?

依次運行：

sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64
sudo chmod +x /usr/local/bin/gitlab-runner

?

備注：這個下載過程可能會很慢，你可以復(fù)制上面的鏈接到瀏覽器中翻墻下載，然后下載完畢再進行后續(xù)處理

?

「2.初始化gitlab-runner」

cd ~
gitlab-runner install
gitlab-runner start

最后輸出如下，說明成功了。

「3.注冊Runner」

運行完gitlab-runner start只是完成了初始化，接下來你還要通過注冊才能運行runner

?

參考鏈接：https://docs.gitlab.com/runner/register/index.html

?

注冊runner只需要一條運行命令：

sudo gitlab-runner register

然后寫入相應(yīng)的token,url和tag等相關(guān)信息，就注冊完畢了。

上面要求輸入的Runner綁定的token和url， 獲取方式如下：

Gitlab項目首頁=> setting => CI/CD => Runners => Specific Runners

「4.激活Runner」

注冊完了可能還需要激活，這時我們可以看下面板，如果有個黑色的感嘆號，這說明runner注冊成功了，但是尚未激活（「如果是綠色的說明已經(jīng)激活，本步驟跳過」）

激活方法是本地運行：

sudo gitlab-runner verify

輸出

這時候回去看Gitlab面板里的Runner參數(shù)：

是綠色就說明激活成功了

「5.梳理和規(guī)劃Pipeline的不同階段和過程」

在編寫.gitlab-ci.yml前，首先需要考慮的是我們的pipeline分幾個階段處理。

從前端工程師的角度出發(fā)，一個前端項目的PipeLine處理包括以下階段

「<1> install階段」

就是執(zhí)行npm install命令,根據(jù)package.json安裝node_modules依賴包

「<2> eslint階段」

執(zhí)行eslint檢查，判斷代碼格式是否符合規(guī)范，如果不符合則pipeline終止。

在這之前，我先通過npm install eslint安裝了eslint檢查工具，然后在項目根目錄下配置了.eslintrc文件。這部分可自行參考相關(guān)資料，這里暫不多贅述。

「<3>build階段」

編譯生成生產(chǎn)代碼，可以通過webpack之類的打包工具執(zhí)行編譯。當然可以通過框架提供的編譯命令進行編譯，例如我這個示例項目是用 react-scripts腳手架搭建的，所以通過npx react-scripts build進行編譯。

「<4>deploy階段」

deploy也就是部署階段，也就是把剛才bulid階段生成的生產(chǎn)代碼，部署到生產(chǎn)訪問的服務(wù)器上。這里又具體有以下兩部分工作要做

「A.申請服務(wù)器 & 安裝web服務(wù) (準備工作)」

（1）我本次使用的是百度云的「云服務(wù)器」(每天9點的時候可以搶有一定免費使用期限的服務(wù)器)

（2）然后在本地終端通過ssh遠程登陸服務(wù)器，并安裝「apache」以提供web服務(wù)

sudo apt-get install apache2

（3）然后，安裝完后的apache會在服務(wù)器下新增**/var/www/html/**目錄， 這個目錄就是存放網(wǎng)站資源的位置。

（4）最后我們只需要在每次部署的時候把生產(chǎn)的單頁面拷貝到這個頁面下，就能在瀏覽器上通過對應(yīng)的 「IP+路徑」來訪問Web頁面了。

「B. 部署資源（每次pipeline都進行）」

我下面的示例中，是通過 「scp」 這一命令，將本地機器代碼遠程拷貝到云服務(wù)器上。

因為這一命令需要輸入密碼，所以通過 「sshpass」 命令攜帶密碼再執(zhí)行scp：

sshpass -p $PASSWORD scp -r ./build $CUSTOM_USERNAME@$CUSTOM_IP:/var/www/html

這里說明一下，「Gitlab有自定義變量的功能」，例如我們覺得直接在YML中寫入密碼/賬號等信息不太好，那么「可以通過美元符號$寫入一個預(yù)定義的變量，然后在Gitlab面板上輸入它」

「7.編寫.gitlab-ci.yml配置文件」

回顧一下之前YML語法規(guī)則和gitlab-ci配置關(guān)鍵字的知識，就不難編寫出以下YML文件

stages: # 分段
  - install
  - eslint
  - build
  - deploy

cache: # 緩存
  paths:
    - node_modules
    - build

install-job:
  tags:
    - sss
  stage: install
  script:
    - npm install

eslint-job:
  tags:
    - sss
  stage: eslint
  script:
    - npm run eslint

build-job:
  tags:
    - sss
  stage: build
  script:
    - npm run build

deploy-job:
  tags:
    - sss
  stage: deploy
  script:
    - sshpass -p $PASSWORD scp -r ./build $CUSTOM_USERNAME@$CUSTOM_IP:/var/www/html

「package.json」如下

{
  ...
  "scripts": {
    "start": "react-scripts start",
    "build": "npx react-scripts build",
    "eslint": "eslint ./src",
  },
  ....
}

「8.提交項目代碼」

OK！終于到最后一步了，commit然后push

可以看到運行如下

跑完后

最后輸入我們部署的IP看看我們部署的網(wǎng)頁

發(fā)現(xiàn)已經(jīng)把我們的項目代碼部署上去了

四. Gitlab-ci坑點詳解

說多了都是淚。。。。。

下面總結(jié)一下使用過程中遇到的典型坑點

「1.Runner未激活問題」

有時候注冊之后，查看面板上的Runner信息，可能會發(fā)現(xiàn)Runner處在未激活狀態(tài)

解決方法：

運行以下命令重新啟動runner

sudo gitlab-runner verify
sudo gitlab-runner restart

「2.Job一直掛起，沒有Runner來處理」

1.首先考慮的是不是Runner沒有激活，如果沒有那么按上面方式處理

2.還可能是tag沒有匹配到，上面說過，Runner注冊時是要填寫綁定tag的，如果你在YML里面編寫Job沒有帶上tag是不會有自定義Runner來處理。解決方法:給Job加tags

3.最后一種可能：你連續(xù)注冊了多個Runner,這些Runner沖突了，或者是新注冊的Runner和舊Runner使用了同一個token,這時候的解決方法如下：

「先刪掉本地其他舊的Runner」

sudo gitlab-runner unregister --all-runners

然后重置token,并使用更新后的token重新注冊一個Runner

「3.specific Runner被Share Runner搶占了Job」

有時候你可能會發(fā)現(xiàn)：你的Job并沒有被你新建的Runner執(zhí)行，而是被Share Runner搶先執(zhí)行了。你如果不想要Share Runner，你可以在Gitlab面板上關(guān)掉

五.gitlab-ci進階

5.1 YML的片段復(fù)用和模塊化

上面我們編寫了gitlab-ci的**"hello world"**。但在實際項目的運行中，.gitlab-ci.yml的編寫可能會漸趨復(fù)雜。那么這個時候YML的一些其他語法功能就派上用場了，上面我們將JSON和YML的基本結(jié)構(gòu)做比較并發(fā)現(xiàn)它們的相似之處，但實際上，「YML提供了比JSON更為豐富的功能?！?/strong>

「YML的片段復(fù)用功能」

「試思考」：如果有一段配置片段會被很多Job使用，那么如果重復(fù)寫入片段，則會使我們的YML文件變得過分冗長。

而如果能把這段提前進行定義，并根據(jù)別名進行導(dǎo)入，就能讓YML文件簡潔很多了。

「YML的語法天然提供了這個功能:」

• 使用 **&**符號可以定義一個片段的別名
• 使用 **<<**符號和 ***** 符號可以將別名對應(yīng)的YML片段導(dǎo)入

.common-config: &commonConfig
  only: # 表示僅在develop/release分支上執(zhí)行
    refs:
      - develop
      - release

install-job:
  # 其他配置 ....
  <<: *commonConfig
build-job:
  # 其他配置 ....
  <<: *commonConfig

「YML的模塊化功能」

試思考，如果我們配置腳本很長的話，我們一定要把它寫在.gitlab-ci.yml這單獨一個文件里嗎？

能否將它分成多個yml文件，然后把其他YML文件導(dǎo)入到入口YML文件(.gitlab-ci.yml)中呢。

gitlab-ci提供的include關(guān)鍵字便可實現(xiàn)這個功能, 它可以用來導(dǎo)入外部的YML文件。

例如我們有如下的YML結(jié)構(gòu)

 ├── .gitlab-ci.h5.yml'
 ├── .gitlab-ci.bd.yml'
 ├── .gitlab-ci.wx.yml
 └── .gitlab-ci.yml

「那么在.gitlab-ci.yml中這么寫，就可以對它們做合并」

include:
  - '/.gitlab-ci.wx.yml'
  - '/.gitlab-ci.bd.yml'
  - '/.gitlab-ci.h5.yml'

gitlab-ci還提供了extend關(guān)鍵字，它的功能和前面提到的YML的片段導(dǎo)入的功能是一樣的，

不過可讀性更好一些。

.common-config: 
  only: # 表示僅在develop/release分支上執(zhí)行
    refs:
      - develop
      - release

install-job:
  # 其他配置 ....
  extends: .common-config

build-job:
  # 其他配置 ....
  extends: .common-config

5.2 Gitlab-ci的其他配置項

「cache關(guān)鍵字」

cache關(guān)鍵字是需要特別著重講的一個關(guān)鍵字。顧名思義，它是用來做緩存的。

為什么要做緩存呢？當然是為了「重復(fù)運行pipeline的時候不會重復(fù)安裝全部node_modules的包」，從而減少pipeline的時間，提高pipeline的性能。

「但是，這并不是cache關(guān)鍵字唯一的功能！」

在介紹cache的另外一個功能之前，我要先說一下gitlab-ci的一個優(yōu)點“惡心人”的特點：

它在運行下一個Job的時候，會默認把前一個Job新增的資源刪除得干干靜靜

沒錯，也就是說，我們上面bulid階段編譯生成的包，會在deploy階段運行前被默認刪除?。ㄎ疑a(chǎn)包都沒了我怎么部署emmmmmmm）

而cache的作用就在這里體現(xiàn)出來了：如果我們把bulid生產(chǎn)的包的路徑添加到cache里面，雖然gitlab還是會刪除bulid目錄，但是因為在刪除前我們已經(jīng)重新上傳了cache，并且在下個Job運行時又把cache給pull下來，那么這個時候就可以實現(xiàn)在下一個Job里面使用前一個Job的資源了

總而言之，cache的功能體現(xiàn)在兩點：

• 「在不同pipeline之間重用資源」
• 「在同一pipeline的不同Job之間重用資源」

雖然cache會緩存舊的包，但我們并不用擔(dān)心使用到舊的資源，因為npm install還是會如期運行，并檢查package.json是否有更新，npm build的時候，生成的build資源包也會覆蓋cache,并且在當前Job運行結(jié)束時，作為**"新的cache"**上傳

artifacts關(guān)鍵字

這個關(guān)鍵字的作用是：將生成的資源作為pipeline運行成功的附件上傳，并在gitlab交互界面上提供下載

例如我們新增以下YML

Build-job:
  stage: build
  script:
  - 'npm run build'
  artifacts:
    name: 'bundle'
    paths: 
      - build/

pipeline跑完后是這樣的：

image/services

這兩個關(guān)鍵字可使用Docker的鏡像和服務(wù)運行Job，具體可參考Docker的相關(guān)資料,這里暫不多加敘述

only/except

這兩個關(guān)鍵字后面跟的值是tag或者分支名的列表。

故名思義

• only的作用是指定當前Job僅僅只在某些tag或者branch上觸發(fā)
• 而except的作用是當前Job不在某些tag或者branch上觸發(fā)

job:
  # use regexp
  only:
    - /^issue-.*$/
    - develop
    - release

allow_failure

值為true/false, 表示當前Job是否允許允許失敗。

• 默認是false,也就是如果當前Job因為報錯而失敗，則當前pipeline停止
• 如果是true，則即使當前Job失敗，pipeline也會繼續(xù)運行下去。

job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true

retry

顧名思義，指明的是當前Job的失敗重試次數(shù)的上限。

但是這個值只能在0 ～2之間，也就是重試次數(shù)最多為2次，包括第一次運行在內(nèi)，Job最多自動運行3次

timeout

配置超時時間，超過時間判定為失敗

Job:
  script: rspec
  timeout: 3h 30m

When

表示當前Job在何種狀態(tài)下運行，它可設(shè)置為3個值

• 「on_success」: 僅當先前pipeline中的所有Job都成功（或因為已標記，被視為成功allow_failure）時才執(zhí)行當前Job 。這是默認值。
• 「on_failure」: 僅當至少一個先前階段的Job失敗時才執(zhí)行當前Job。
• 「always」: 執(zhí)行當前Job，而不管先前pipeline的Job狀態(tài)如何。