持續集成-通過 .gitlab-ci.yml配置任務

持續集成-通過 .gitlab-ci.yml配置任務

出處說明

關於.gitlab-ci.yml配置任務的中文資料和文檔較少，找了很久，才找到一個準確而又系統的文檔。大家可以下載。鏈接

我對一些關鍵地方會做相應註解，這些是基於實踐的經驗累積。有問題可以相互討論指出。

.gitlab-ci.yml

script

可以想成自己在做每一個任務時，用的shell指令的整個過程。比如我要燒錄一個.bin文件到開發板中，我會先編譯（make）,再燒錄（make flash）。那麼，我的script如下：

job1:
  script: 
    - make
    - make flash

script可以直接執行系統命令(例如：./configure;make;make install)或者是直接執行腳本(test.sh)。

job

開始構建之前YAML文件定義了一系列帶有約束說明的任務(job)。這些任務都是以任務名開始並且至少要包含script部分：

job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"

上面這個例子就是一個最簡單且帶有兩個獨立任務的CI配置，每個任務分別執行不同的命令。

任務是由Runners接管並且由服務器中runner執行。更重要的是，每一個任務的執行過程都是獨立運行的。

**爲什麼要有job？
個人的理解是job是繼承的“元”， 並且同一stage的job是可以並行的，大大提高了集成效率。並且job可以友好的對整個過程分類，如環境（硬件或軟件）不同，是一個非常好的管理繼承過程的方式。
**

用下面這個例子來說明YAML語法還有更多複雜的任務：

image: ruby:2.1
services:
  - postgres

before_script:
  - bundle install

after_script:
  - rm secrets

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - execute-script-for-job1
  only:
    - master
  tags:
    - docker

下面列出保留字段，這些保留字段不能被定義爲job名稱：

關鍵字	是否必須	描述
image	否	用於docker鏡像，查看docker文檔
services	否	用於docker服務，查看docker文檔
stages	否	定義構建階段
types	否	stages 的別名(已廢除)
before_script	否	定義在每個job之前運行的命令
after_script	否	定義在每個job之後運行的命令
variable	否	定義構建變量
cache	否	定義一組文件列表，可在後續運行中使用

image和services

這兩個關鍵字允許使用一個自定義的Docker鏡像和一系列的服務，並且可以用於整個job週期。詳細配置文檔請查看a separate document。

before_script

before_script用來定義所有job之前運行的命令，包括deploy(部署) jobs，但是在修復artifacts之後。它可以是一個數組或者是多行字符串。

**這句話個人覺得可能稍有偏頗。
實際上所謂的before_script需要和script結合起來看，before_script是在script步驟之前運行的。既然有了script，爲什麼還需要before_script呢？是因爲在集成過程中，有很多的準備工作是一致的，那麼可以提前定義好before_script。之後， 所有job會默認自動先執行完before_script的內容，再來運行自身的script。
那麼如果有job不需要這個呢？在今後我會講解到的。
after_script同理。**

after_script

after_script用來定義所有job之後運行的命令。它必須是一個數組或者是多行字符串

stages

stages用來定義可以被job調用的stages。stages的規範允許有靈活的多級pipelines。

stages中的元素順序決定了對應job的執行順序：

1. 相同stage的job可以平行執行。
2. 下一個stage的job會在前一個stage的job成功後開始執行。

接下仔細看看這個例子，它包含了3個stage：

stages:
 - build
 - test
 - deploy

1. 首先，所有build的jobs都是並行執行的。
2. 所有build的jobs執行成功後，test的jobs纔會開始並行執行。
3. 所有test的jobs執行成功，deploy的jobs纔會開始並行執行。
4. 所有的deploy的jobs執行成功，commit纔會標記爲success
5. 任何一個前置的jobs失敗了，commit會標記爲failed並且下一個stages的jobs都不會執行。

這有兩個特殊的例子值得一提：

1. 如果.gitlab-ci.yml中沒有定義stages，那麼job’s stages 會默認定義爲 build，test 和 deploy。
2. 如果一個job沒有指定stage，那麼這個任務會分配到test stage。

types

已廢除，將會在10.0中移除。用stages替代。

與stages同義

variables

GitLab Runner V0.5.0. 開始引入

GItLab CI 允許在.gitlab-ci.yml文件中添加變量，並在job環境中起作用。因爲這些配置是存儲在git倉庫中，所以最好是存儲項目的非敏感配置，例如：

variables:
  DATABASE_URL:"postgres://postgres@postgres/my_database"

這些變量可以被後續的命令和腳本使用。服務容器也可以使用YAML中定義的變量，因此我們可以很好的調控服務容器。變量也可以定義成job level。

除了用戶自定義的變量外，Runner也可以定義它自己的變量。CI_COMMIT_REG_NAME就是一個很好的例子，它的值表示用於構建項目的分支或tag名稱。除了在.gitlab-ci.yml中設置變量外，還有可以通過GitLab的界面上設置私有變量。

更多關於variables。

cache

Gitlab Runner v0.7.0 開始引入。

cache用來指定需要在job之間緩存的文件或目錄。只能使用該項目工作空間內的路徑。

從GitLab 9.0開始，pipelines和job就默認開啓了緩存

如果cache定義在jobs的作用域之外，那麼它就是全局緩存，所有jobs都可以使用該緩存。

緩存binaries和.config中的所有文件：

rspec:
  script: test
  cache:
    paths:
    - binaries/
    - .config

緩存git中沒有被跟蹤的文件：

rspec:
  script: test
  cache:
    untracked: true

緩存binaries下沒有被git跟蹤的文件：

rspec:
  script: test
  cache:
    untracked: true
    paths:
    - binaries/

job中優先級高於全局的。下面這個rspecjob中將只會緩存binaries/下的文件：

cache:
  paths:
  - my/files

rspec:
  script: test
  cache:
    key: rspec
    paths:
    - binaries/

注意，緩存是在jobs之前進行共享的。如果你不同的jobs緩存不同的文件路徑，必須設置不同的cache:key，否則緩存內容將被重寫。

緩存只是盡力而爲之，所以別期望緩存會一直存在。查看更多詳細內容，請查閱GitLab Runner。

事實上cache在實際的實踐過程中用的很少，用的更多的是與之類似的artifacts。兩者差別在於artifacts可以在job之間類似於變量一樣進行傳遞。也就是說在這個job緩存的內容可以在別的job中使用，而cache無法做到這一點。關於artifacts會在下文介紹。

緩存key

GitLab Runner v1.0.0 開始引入。

key指令允許我們定義緩存的作用域(親和性)，可以是所有jobs的單個緩存，也可以是每個job，也可以是每個分支或者是任何你認爲合適的地方。

它也可以讓你很好的調整緩存，允許你設置不同jobs的緩存，甚至是不同分支的緩存。

cache:key可以使用任何的預定義變量。

默認key是默認設置的這個項目緩存，因此默認情況下，每個pipelines和jobs中可以共享一切，從GitLab 9.0開始。

配置示例

緩存每個job：

cache:
  key: "$CI_JOB_NAME"
  untracked: true

緩存每個分支：

cache:
  key: "$CI_COMMIT_REF_NAME"
  untracked: true

緩存每個job且每個分支：

cache:
  key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME"
  untracked: true

緩存每個分支且每個stage：

cache:
  key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME"
  untracked: true

如果使用的Windows Batch(windows批處理)來跑腳本需要用%替代$：

cache:
  key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%"
  untracked: true

Jobs

.gitlab-ci.yml允許指定無限量jobs。每個jobs必須有一個唯一的名字，而且不能是上面提到的關鍵字。job由一列參數來定義jobs的行爲。

job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true

Keyword	Required	Description
script	yes	Runner執行的命令或腳本
image	no	所使用的docker鏡像，查閱使用docker鏡像
services	no	所使用的docker服務，查閱使用docker鏡像
stage	no	定義job stage（默認：test）
type	no	stage的別名（已棄用）
variables	no	定義job級別的變量
only	no	定義一列git分支，併爲其創建job
except	no	定義一列git分支，不創建job
tags	no	定義一列tags，用來指定選擇哪個Runner（同時Runner也要設置tags）
allow_failure	no	允許job失敗。失敗的job不影響commit狀態
when	no	定義何時開始job。可以是on_success，on_failure，always或者manual
dependencies	no	定義job依賴關係，這樣他們就可以互相傳遞artifacts
cache	no	定義應在後續運行之間緩存的文件列表
before_script	no	重寫一組在作業前執行的命令
after_script	no	重寫一組在作業後執行的命令
environment	no	定義此作業完成部署的環境名稱
coverage	no	定義給定作業的代碼覆蓋率設置

script

script是Runner執行的yaml腳本。舉個例子：

job:
  script: "bundle exec rspec"

該參數也可以用數組包含多個命令：

job:
  script:
    - uname -a
    - bundle exec rspec

有時候，script命令需要被單引號或者是雙引號包裹起來。舉個例子，當命令中包含冒號(:)時，script需要被包在雙引號中，這樣YAML解析器纔可以正確解析爲一個字符串而不是一個鍵值對(key:value)。使用這些特殊字符的時候一定要注意：:,{,},[,],,,&,*,#,?,|,-,<,>,=,!。

stage

stage允許一組jobs進入不同的stages。jobs在相同的stage時會parallel同時進行。查閱stages更多的用法請查看stages。

only and except

only和except是兩個參數用分支策略來限制jobs構建：

1. only定義哪些分支和標籤的git項目將會被job執行。
2. except定義哪些分支和標籤的git項目將不會被job執行。

下面是refs策略的使用規則：

• only和except可同時使用。如果only和except在一個job配置中同時存在，則以only爲準，跳過except(從下面示例中得出)。
• only和except可以使用正則表達式。
• only和except允許使用特殊的關鍵字：branches，tags和triggers。
• only和except允許使用指定倉庫地址但不是forks的倉庫(查看示例3)。

在下面這個例子中，job將只會運行以issue-開始的refs(分支)，然而except中設置將被跳過。

job:
  # use regexp
  only:
    - /^issue-.*$/
  # use special keyword
  except:
    - branches

在下面這個例子中，job將只會執行有tags的refs，或者通過API觸發器明確地請求構建。

job:
  # use special keywords
  only:
    - tags
    - triggers

倉庫路徑只能用於父級倉庫執行jobs，而不是forks：

job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce

上面這個例子將會爲所有的分支執行job，但master分支除外。

Job variables

在job中是可以使用關鍵字variables來定義job變量。它的運行原理跟global-level是一樣的，但是它允許設置特殊的job變量。

當設置了job級別的關鍵字variables，它會覆蓋全局YAML和預定義中的job變量。想要關閉全局變量可以在job中設置一個空數組：

job_name:
  variables: []

Job變量的優先級關係可查看variables文檔說明。

tags

tags可以從允許運行此項目的所有Runners中選擇特定的Runners來執行jobs。

在註冊Runner的過程中，我們可以設置Runner的標籤，比如ruby，postgres，development。

tags可通過tags來指定特殊的Runners來運行jobs：

job:
  tags:
    - ruby
    - postgres

上面這個示例中，需要確保構建此job的Runner必須定義了ruby和postgres這兩個tags。

allow_failure

allow_failure可以用於當你想設置一個job失敗的之後並不影響後續的CI組件的時候。失敗的jobs不會影響到commit狀態。

當開啓了允許job失敗，所有的intents和purposes裏的pipeline都是成功/綠色，但是也會有一個”CI build passed with warnings”信息顯示在merge request或commit或job page。這被允許失敗的作業使用，但是如果失敗表示其他地方應採取其他（手動）步驟。

下面的這個例子中，job1和job2將會並列進行，如果job1失敗了，它也不會影響進行中的下一個stage，因爲這裏有設置了allow_failure: true。

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

job2:
  stage: test
  script:
  - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
  - deploy_to_staging

when

when is used to implement jobs that are run in case of failure or despite the failure.

when可以設置以下值：

1. on_success - 只有前面stages的所有工作成功時才執行。 這是默認值。
2. on_failure - 當前面stages中任意一個jobs失敗後執行。
3. always - 無論前面stages中jobs狀態如何都執行。
4. `manual ` - 手動執行(GitLab8.10增加)。更多請查看手動操作。

舉個例子：

stages:
- build
- cleanup_build
- test
- deploy
- cleanup

build_job:
  stage: build
  script:
  - make build

cleanup_build_job:
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
  - make test

deploy_job:
  stage: deploy
  script:
  - make deploy
  when: manual

cleanup_job:
  stage: cleanup
  script:
  - cleanup after jobs
  when: always

腳本說明：

1. 只有當build_job失敗的時候纔會執行`cleanup_build_job 。
2. 不管前一個job執行失敗還是成功都會執行`cleanup_job 。
3. 可以從GitLab界面中手動執行deploy_jobs。

Manual actions

GitLab 8.10 開始引入手動執行。GitLab 9.0 開始引入手動停止。GitLab 9.2 開始引入保護手動操作。

手動操作指令是不自動執行的特殊類型的job；它們必須要人爲啓動。手動操作指令可以從pipeline，build，environment和deployment視圖中啓動。

部署到生產環境是手動操作指令的一個很好示例。

瞭解更多請查看environments documentation。

手動操作指令可以是可選的或阻塞。在定義了手動執行的那個stage中，手動操作指令將會停止pipline中的自動執行指令。當有人通過點擊play按鈕來執行需要手動執行的job時，可以來恢復pipeline的執行。

當pipeline被阻塞時，即使是pipeline是成功狀態也不會merge。被阻塞的pipelines也有一個特殊的狀態，叫manual。

手動操作指令默認是不阻塞的。如果你想要手動操作指令產生阻塞，首先需要在job的配置文件.gitlab-ci.yml中添加allow_failure:false。

可選的手動操作指令默認設置allow_failure:true。

可選動作的狀態不影響整個pipeline的狀態。

手動操作指令被認爲是寫操作，所以當前用戶觸發操作時，必須擁有操作保護分支的權限。換句話說，爲了觸發一個手動操作指令到pipeline中正在運行的指定分支，當前用戶必須擁有推送到這分支的權限。

enviroment

注意：

• GitLab 8.9 開始引入。
• 更多關於environment說明或者示例可以查看 documentation about environments。

environment用於定義job部署到特殊的環境中。如果指定了environment，並且沒有該名稱下的環境，則會自動創建新環境。

在最簡單的格式中，環境關鍵字可以定義爲：

deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production

在上面這個例子中，deploy to profuctionjob將會執行部署到production環境的操作。

environment:name

注意

• GitLab 8.11 開始引入。
• 在GitLab8.11之前，環境名稱定義爲environment:production。現在推薦的做法是定義爲name關鍵字。

environment名稱可以包含：

• 英文字母(letters)
• 數字(digits)
• 空格(spaces)
• -
• _
• /
• $
• {
• }

常用的名稱有qa,staging，和production，當然你可以在你的工作流中使用任意名字。

除了在environment關鍵字右邊緊跟name定義方法外，也是可以爲環境名稱單獨設定一個值。例如，用name關鍵字在environment下面設置：

deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production

environment:url

注意：

• GitLab 8.11 開始引用。
• 在GitLab 8.11之前，URL只能在GitLab’s UI中添加。現在推薦的定義方法是在.gitlab-ci.yml。

這是設置一個可選值，它會顯示在按鈕中，點擊它可以帶你到設置的URL頁面。

在下面這個例子中，如果job都成功完成了，在environment/deployments頁面中將會創建一個合併請求的按鈕，它將指向https://prod.example.com。

deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
    name: production
    url: https://prod.example.com

environment:on_stop

注意：

• GitLab 8.13中開始引入。
• 從GitLab 8.14開始，當在environment中定義了一個stop操作，GitLab將會在相關聯的分支本刪除時自動觸發一個stop操作。

關閉(停止)environments可以通過在environment下定義關鍵字on_stop來實現。它定義了一個不同的job，用於關閉environment。

請查看environment:action模塊中例子。

environment:action

Gitlab 8.13 開始引入。

action和on_stop聯合使用，定義在job中，用來關閉environment。

舉個例子：

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
  script: make delete-app
  when: manual
  environment:
    name: review
    action: stop

上面這個例子中，我們定義了review_appjob來部署到review環境中，同時我們也定義了一個新stop_review_appjob在on_stop中。一旦review_appjob執行完成並且成功，它將觸發定義在when中的stop_review_appjob。在這種情況下，我們設置爲manual，需要通過GitLab’s web界面來允許manual action。

stop_review_appjob需要定義下面這些關鍵字：

• when - 說明
• environment:name
• environment:action
• stage需要和review_app相同，以便分支刪除被刪除的時候自動執行停止。

dynamic environment

注意：

• GitLab 8.12開始引入，並且要求GitLab Runner 1.6 。
• GitLab 8.15開始引入$CI_ENVIRONMENT_SLUG。

environment也可以是代表配置項，其中包含name和url。這些參數可以使用任何的CI variables(包括預定義、安全變量和.gitlab-ci.yml中的變量)。

舉個例子：

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

當$CI_COMMIT_REF_NAME 被Runner設置爲environment variable時，deply as review appjob將會被指定部署到動態創建revuew/$CI_COMMIT_REF_NAME的環境中。$CI_ENVIRONMENT_SLUG變量是基於環境名稱的，最終組合成完整的URLs。在這種情況下，如果deploy as review appjob是運行在名稱爲pow的分支下，那麼可以通過URLhttps"//review-pw.example.com/來訪問這個環境。

這當然意味着託管應用程序的底層服務器已經正確配置。

常見的做法是爲分支創建動態環境，並講它們作爲Review Apps。可以通過https://gitlab.com/gitlab-examples/review-apps-nginx/上查看使用Review Apps的簡單示例。

artifacts

**
在這裏我希望讓大家提前注意到一點，如先前所說，artifacts是可以在job之間傳遞的，然而是隻能向之後的stage傳遞！原因也很簡單，希望大家理解，如我先前所說，同一stage的job是並行的，那麼同一stage的job之間是無法做到傳遞artifacts的。
**

artifacts用於指定成功後應附加到job的文件和目錄的列表。只能使用項目工作間內的文件或目錄路徑。如果想要在不通的job之間傳遞artifacts，請查閱依賴關係。以下是一些例子：

發送binaries和.config中的所有文件：

artifacts:
  paths:
  - binaries/
  - .config

發送所有沒有被Git跟蹤的文件：

artifacts:
  untracked: true

發送沒有被Git跟蹤和binaries中的所有文件：

artifacts:
  untracked: true
  paths:
  - binaries/

定義一個空的dependencies可以禁用artifact傳遞：

job:
  stage: build
  script: make build
  dependencies: []

有時候只需要爲標籤爲releases創建artifacts，以避免將臨時構建的artifacts傳遞到生產服務器中。

只爲tags創建artifacts（default-job將不會創建artifacts）：

default-job:
  script:
    - mvn test -U
  except:
    - tags

release-job:
  script:
    - mvn package -U
  artifacts:
    paths:
    - target/*.war
  only:
    - tags

在job成功完成後artifacts將會發送到GitLab中，同時也會在GitLab UI中提供下載。

artifacts:name

GitLab 8.6 和 Runner v1.1.0 引入。

name允許定義創建的artifacts存檔的名稱。這樣一來，我們可以爲每個存檔提供一個唯一的名稱，當需要從GitLab中下載是纔不會混亂。artifacts:name可以使用任何的預定義變量(predefined variables)。它的默認名稱爲artifacts，當下載是就變成了artifacts.zip。

---

配置示例

通過使用當前job的名字作爲存檔名稱：

job:
  artifacts:
    name: "$CI_JOB_NAME"

使用當前分支名稱或者是tag作爲存到名稱，只存檔沒有被Git跟蹤的文件：

job:
   artifacts:
     name: "$CI_COMMIT_REF_NAME"
     untracked: true

使用當前job名稱和當前分支名稱或者是tag作爲存檔名稱，只存檔沒有被Git跟蹤的文件：

job:
  artifacts:
    name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}"
    untracked: true

使用當前stage和分支名稱作爲存檔名稱：

job:
  artifacts:
    name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}"
    untracked: true

如果是使用Windows批處理來運行yaml腳本，需要用%替換$：

job:
  artifacts:
    name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%"
    untracked: true

artifacts:when

GitLab 8.9和GitLab Runner v1.3.0 引入。

在job失敗的時候，artifacts:when用來上傳artifacts或者忽略失敗。

artifacts:when可以設置一下值：

1. on_success - 當job成功的時候上傳artifacts。默認值。
2. on_failure - 當job失敗的時候上傳artifacts。
3. always - 不論job失敗還是成功都上傳artifacts。

---

示例配置

只在job失敗的時候上傳artifacts。

job:
  artifacts:
    when: on_failure

artifacts:expire_in

GitLab 8.9 和 GitLab Runner v1.3.0 引入。

artifacts:expire_in用於過期後刪除郵件上傳的artifacts。默認情況下，artifacts都是在GitLab中永久保存。expire_in允許設置設置artifacts的存儲時間，從它們被上傳存儲到GitLab開始計算。

可以通過job頁面的Keep來修改有效期。

過期後，artifacts會被通過一個默認每小時執行一次的定時job刪除，所以在過期後無法訪問artifacts。

expire_in是一個時間區間。下面可設置的值：

• ‘3 mins 4 sec’
• ‘2 hrs 20 min’
• ‘2h20min’
• ‘6 mos 1 day’
• ‘47 yrs 6 mos and 4d’
• ‘3 weeks and 2 days’

---

示例配置

設置artifacts的有效期爲一個星期：

job:
  artifacts:
    expire_in: 1 week

dependencies

GitLab 8.6 和 GitLab RUnner v1.1.1引入。

這個功能應該與artifacts一起使用，並允許定義在不同jobs之間傳遞artifacts。

注意：所有之前的stages都是默認設置通過。

如果要使用此功能，應該在上下文的job中定義dependencies，並且列出之前都已經通過的jobs和可下載的artifacts。你只能在當前執行的stages前定義jobs。你如果在當前stages或者後續的stages中定義了jobs，它將會報錯。可以通過定義一個空數組是當前job跳過下載artifacts。

---

在接下來的例子中，我們定義兩個帶artifacts的jobs，build:osx和build:linux。當test:osx開始執行的時候，build:osx的artifacts就會開始下載並且會在build的stages下執行。同樣的會發生在test:linux，從build:linux中下載artifacts。

因爲stages的優先級關係，deployjob將會下載之前jobs的所有artifacts：

build:osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
    - binaries/

build:linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
    - binaries/

test:osx:
  stage: test
  script: make test:osx
  dependencies:
  - build:osx

test:linux:
  stage: test
  script: make test:linux
  dependencies:
  - build:linux

deploy:
  stage: deploy
  script: make deploy

before_script 和 after_script

它可能會覆蓋全局定義的before_script和after_script：

before_script:
- global before script

job:
  before_script:
  - execute this instead of global before script
  script:
  - my command
  after_script:
  - execute this after my script

coverage

注意：

GitLab 8.17 引入。

coverage允許你配置代碼覆蓋率將會從該job中提取輸出。

在這裏正則表達式是唯一有效的值。因此，字符串的前後必須使用/包含來表明一個正確的正則表達式規則。特殊字符串需要轉義。

一個簡單的例子：

job1:
  coverage: '/Code coverage: \d+\.\d+/'

Git Strategy

GitLab 8.9中以試驗性功能引入。將來的版本中可能改變或完全移除。GIT_STRATEGY要求GitLab Runner v1.7+。

你可以通過設置GIT_STRATEGY用於獲取最新的代碼，可以再全局variables或者是在單個job的variables模塊中設置。如果沒有設置，將從項目中使用默認值。

可以設置的值有：clone，fetch，和none。

clone是最慢的選項。它會從頭開始克隆整個倉庫，包含每一個job，以確保項目工作區是最原始的。

variables:
  GIT_STRATEGY: clone

當它重新使用項目工作區是，fetch是更快（如果不存在則返回克隆）。git clean用於撤銷上一個job做的任何改變，git fetch用於獲取上一個job到現在的的commit。

variables:
  GIT_STRATEGY: fetch

none也是重新使用項目工作區，但是它會跳過所有的Git操作（包括GitLab Runner前的克隆腳本，如果存在的話）。它主要用在操作job的artifacts（例如：deploy）。Git數據倉庫肯定是存在的，但是他肯定不是最新的，所以你只能依賴於從項目工作區的緩存或者是artifacts帶來的文件。

variables:
  GIT_STRATEGY: none

Git Checout

GitLab Runner 9.3 引入。

當GIT_STRATEGY設置爲clone或fetch時，可以使用GIT_CHECKOUT變量來指定是否應該運行git checkout。如果沒有指定，它默認爲true。就像GIT_STRATEGY一樣，它可以設置在全局variables或者是單個job的variables中設置。

如果設置爲false，Runner就會：

• fetch - 更新倉庫並在當前版本中保留工作副本，
• clone - 克隆倉庫並在默認分支中保留工作副本。

Having this setting set to true will mean that for both clone and fetch strategies the Runner will checkout the working copy to a revision related to the CI pipeline:

【如果設置這個爲true將意味着clone和fetch策略都會讓Runner執行項目工作區更新到最新：】

variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: false
script:
  - git checkout master
  - git merge $CI_BUILD_REF_NAME

Git Submodule Strategy

需要GitLab Runner v1.10+。

GIT_SUBMODULE_STRATEGY變量用於在構建之前拉取代碼時，Git子模塊是否或者如何被引入。就像GIT_STRATEGY一樣，它可在全局variables或者是單個job的variables模塊中設置。

它的可用值有：none，normal和recursive：

• none意味着在拉取項目代碼時，子模塊將不會被引入。這個是默認值，與v1.10之前相同的。
• normal意味着在只有頂級子模塊會被引入。它相當於：

git submodule sync
git submodule update --init

recursive意味着所有的子模塊（包括子模塊的子模塊）都會被引入，他相當於：

git submodule sync --recursive
git submodule update --init --recursive

注意：如果想要此功能正常工作，子模塊必須配置（在.gitmodules）下面中任意一個：

• 可訪問的公共倉庫http(s)地址，
• 在同一個GitLab服務器上有一個可訪問到另外的倉庫的真實地址。更多查看Git 子模塊文檔。

Job stages attempts

GitLab引入，要求GItLab Runner v1.9+。

正在執行的job將會按照你設置嘗試次數依次執行下面的stages：

變量	描述
GET_SOURCES_ATTEMPTS	獲取job源的嘗試次數
ARTIFACT_DOWNLOAD_ATTEMPTS	下載artifacts的嘗試次數
RESTORE_CACHE_ATTEMPTS	重建緩存的嘗試次數

默認是一次嘗試。

例如：

variables:
  GET_SOURCES_ATTEMPTS: 3

你可以在全局variables模塊中設置，也可以在單個job的variables模塊中設置。

Shallow cloning

GitLab 8.9 以實驗性功能引入。在將來的版本中有可能改變或者完全移除。

你可以通過GIT_DEPTH來指定抓取或克隆的深度。它可淺層的克隆倉庫，這可以顯著加速具有大量提交和舊的大型二進制文件的倉庫的克隆。這個設置的值會傳遞給git fetch和git clone。

注意：如果設置depth=1，並且有一個jobs隊列或者是重試jobs，則jobs可能會失敗。

由於Git抓取和克隆是基於一個REF，例如分支的名稱，所以Runner不能指定克隆一個commit SHA。如果隊列中有多個jobs，或者您正在重試舊的job，則需要測試的提交應該在克隆的Git歷史記錄中存在。設置GIT_DEPTH太小的值可能會導致無法運行哪些舊的commits。在job日誌中可以查看unresolved reference。你應該考慮設置GIT_DEPTH爲一個更大的值。

當GIT_DEPTH只設置了部分存在的記錄時，哪些依賴於git describe的jobs也許不能正確的工作。

只抓取或克隆最後的3次commits：

variables:
  GIT_DEPTH: "3"

Hidden keys

GitLab 8.6 和 GitLab Runner v1.1.1引入。

Key 是以.開始的，GitLab CI 將不會處理它。你可以使用這個功能來忽略jobs，或者用Special YAML features 轉換隱藏鍵爲模版。

在下面這個例子中，.key_name將會被忽略：

.key_name:
  script:
    - rake spec

Hidden keys 可以是像普通CI jobs一樣的哈希值，但你也可以利用special YAMLfeatures來使用不同類型的結構。

Special YAML features

使用special YAML features 像anchors(&)，aliases(*)和map merging(<<)，這將使您可以大大降低.gitlab-ci.yml的複雜性。

查看更多YAML features。

Anchors

GitLab 8.6 和 GitLab Runner v1.1.1引入。

YAML有個方便的功能稱爲”錨”,它可以讓你輕鬆的在文檔中複製內容。Anchors可用於複製/繼承屬性，並且是使用hidden keys來提供模版的完美示例。

下面這個例子使用了anchors和map merging。它將會創建兩個jobs，test1和test2，該jobs將集成.job_template的參數，每個job都自定義腳本：

.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
  script:
    - test1 project

test2:
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
  script:
    - test2 project

&在anchor的名稱(job_definition)前設置，<<表示”merge the given hash into the current one”，*包括命名的anchor(job_definition)。擴展版本如下：

.job_template:
  image: ruby:2.1
  services:
    - postgres
    - redis

test1:
  image: ruby:2.1
  services:
    - postgres
    - redis
  script:
    - test1 project

test2:
  image: ruby:2.1
  services:
    - postgres
    - redis
  script:
    - test2 project

讓我們來看另外一個例子。這一次我們將用anchors來定義兩個服務。兩個服務會創建兩個job，test:postgres和test:mysql，他們會在.job_template中共享定義的script指令，以及分別在.postgres_services和.mysql_services中定義的service指令：

.job_template: &job_definition
  script:
    - test project

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

.mysql_services:
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
  <<: *job_definition
  services: *postgres_definition

test:mysql:
  <<: *job_definition
  services: *mysql_definition

擴展版本如下：

.job_template:
  script:
    - test project

.postgres_services:
  services:
    - postgres
    - ruby

.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
  script:
    - test project
  services:
    - postgres
    - ruby

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby

你可以看到hidden keys被方便的用作模版。

Triggers

Triggers 可用於強制使用API調用重建特定分支，tag或commits。

在triggers文檔中查看更多。

pages

pages是一個特殊的job，用於將靜態的內容上傳到GitLab，可用於爲您的網站提供服務。它有特殊的語法，因此必須滿足以下兩個要求：

1. 任何靜態內容必須放在public/目錄下
2. artifacts必須定義在public/目錄下

下面的這個例子是將所有文件從項目根目錄移動到public/目錄。.public工作流是cp，並且它不會循環複製public/本身。

pages:
  stage: deploy
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

更多內容請查看GitLab Pages用戶文檔。

Validate the .gitlab-ci.yml

GitLab CI的每個實例都有一個名爲Lint的嵌入式調試工具。 你可以在gitlab實例的/ci/lint下找到該鏈接。

Skipping jobs

如果你的commit信息中包含[ci skip]或者[skip ci]，不論大小寫，那麼這個commit將會創建但是jobs也會跳過。

Examples

訪問examples README來查看各種語言的GitLab CI用法示例。

官方文檔地址：https://docs.gitlab.com/ce/ci/yaml/README.html