Gitlab CI 配置檔案 .gitlab-ci.yaml 詳解（下）
本文件是描述 .gitlab-ci.yml 詳細用法的下半部分，上半部分的內容請參考這裡。.gitlab-ci.yml 檔案被用來管理專案的 runner 任務。如果想要快速的瞭解GitLab CI ，可檢視 ofollow,noindex" target="_blank">快速引導 。 該檔案存放於專案倉庫的根目錄，它定義該專案如何構建。
參考閱讀： Gitlab CI 配置檔案 .gitlab-ci.yaml 詳解（上）
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 可以設定一下值：
on_success on_failure always
示例配置
只在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的優先順序關係， deploy job將會下載之前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 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，可用於為您的網站提供服務。它有特殊的語法，因此必須滿足以下兩個要求：
- 任何靜態內容必須放在
public/目錄下 -
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用法示例。