來源：https://github.com/Fennay/git...

此文檔用于描述.gitlab-ci.yml語法，.gitlab-ci.yml文件被用來管理項(xiàng)目的runner 任務(wù)。
如果想要快速的了解GitLab CI ，可查看快速引導(dǎo)。

.gitlab-ci.yml

從7.12版本開始，GitLab CI使用YAML文件(.gitlab-ci.yml)來管理項(xiàng)目配置。該文件存放于項(xiàng)目倉庫的根目錄，它定義該項(xiàng)目如何構(gòu)建。

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

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

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

上面這個(gè)例子就是一個(gè)最簡單且?guī)в袃蓚€(gè)獨(dú)立任務(wù)的CI配置，每個(gè)任務(wù)分別執(zhí)行不同的命令。

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

任務(wù)是由Runners接管并且由服務(wù)器中runner執(zhí)行。更重要的是，每一個(gè)任務(wù)的執(zhí)行過程都是獨(dú)立運(yùn)行的。

用下面這個(gè)例子來說明YAML語法還有更多復(fù)雜的任務(wù)：

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和services

這兩個(gè)關(guān)鍵字允許使用一個(gè)自定義的Docker鏡像和一系列的服務(wù)，并且可以用于整個(gè)job周期。詳細(xì)配置文檔請查看a separate document。

before_script

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

after_script

GitLab 8.7 開始引入，并且要求Gitlab Runner v1.2

after_script用來定義所有job之后運(yùn)行的命令。它必須是一個(gè)數(shù)組或者是多行字符串

stages

stages用來定義可以被job調(diào)用的stages。stages的規(guī)范允許有靈活的多級pipelines。

stages中的元素順序決定了對應(yīng)job的執(zhí)行順序：

1. 相同stage的job可以平行執(zhí)行。
2. 下一個(gè)stage的job會(huì)在前一個(gè)stage的job成功后開始執(zhí)行。

接下仔細(xì)看看這個(gè)例子，它包含了3個(gè)stage：

stages:
 - build
 - test
 - deploy

1. 首先，所有build的jobs都是并行執(zhí)行的。
2. 所有build的jobs執(zhí)行成功后，test的jobs才會(huì)開始并行執(zhí)行。
3. 所有test的jobs執(zhí)行成功，deploy的jobs才會(huì)開始并行執(zhí)行。
4. 所有的deploy的jobs執(zhí)行成功，commit才會(huì)標(biāo)記為success
5. 任何一個(gè)前置的jobs失敗了，commit會(huì)標(biāo)記為failed并且下一個(gè)stages的jobs都不會(huì)執(zhí)行。

這有兩個(gè)特殊的例子值得一提：

1. 如果.gitlab-ci.yml中沒有定義stages，那么job's stages 會(huì)默認(rèn)定義為 build，test 和 deploy。
2. 如果一個(gè)job沒有指定stage，那么這個(gè)任務(wù)會(huì)分配到test stage。

types

已廢除，將會(huì)在10.0中移除。用stages替代。

與stages同義

variables

GitLab Runner V0.5.0. 開始引入

GItLab CI 允許在.gitlab-ci.yml文件中添加變量，并在job環(huán)境中起作用。因?yàn)檫@些配置是存儲(chǔ)在git倉庫中，所以最好是存儲(chǔ)項(xiàng)目的非敏感配置，例如：

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

這些變量可以被后續(xù)的命令和腳本使用。服務(wù)容器也可以使用YAML中定義的變量，因此我們可以很好的調(diào)控服務(wù)容器。變量也可以定義成job level。

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

更多關(guān)于variables。

cache

Gitlab Runner v0.7.0 開始引入。

cache用來指定需要在job之間緩存的文件或目錄。只能使用該項(xiàng)目工作空間內(nèi)的路徑。

從GitLab 9.0開始，pipelines和job就默認(rèn)開啟了緩存

如果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中優(yōu)先級高于全局的。下面這個(gè)rspecjob中將只會(huì)緩存binaries/下的文件：

cache:
  paths:
  - my/files

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

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

緩存只是盡力而為之，所以別期望緩存會(huì)一直存在。查看更多詳細(xì)內(nèi)容，請查閱GitLab Runner。

緩存key

GitLab Runner v1.0.0 開始引入。

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

它也可以讓你很好的調(diào)整緩存，允許你設(shè)置不同jobs的緩存，甚至是不同分支的緩存。

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

默認(rèn)key是默認(rèn)設(shè)置的這個(gè)項(xiàng)目緩存，因此默認(rèn)情況下，每個(gè)pipelines和jobs中可以共享一切，從GitLab 9.0開始。

配置示例

緩存每個(gè)job：

cache:
  key: "$CI_JOB_NAME"
  untracked: true

緩存每個(gè)分支：

cache:
  key: "$CI_COMMIT_REF_NAME"
  untracked: true

緩存每個(gè)job且每個(gè)分支：

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

緩存每個(gè)分支且每個(gè)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。每個(gè)jobs必須有一個(gè)唯一的名字，而且不能是上面提到的關(guān)鍵字。job由一列參數(shù)來定義jobs的行為。

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

script

script是Runner執(zhí)行的yaml腳本。舉個(gè)例子：

job:
  script: "bundle exec rspec"

該參數(shù)也可以用數(shù)組包含多個(gè)命令：

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

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

stage

stage允許一組jobs進(jìn)入不同的stages。jobs在相同的stage時(shí)會(huì)parallel同時(shí)進(jìn)行。查閱stages更多的用法請查看stages。

only and except

only和except是兩個(gè)參數(shù)用分支策略來限制jobs構(gòu)建：

1. only定義哪些分支和標(biāo)簽的git項(xiàng)目將會(huì)被job執(zhí)行。
2. except定義哪些分支和標(biāo)簽的git項(xiàng)目將不會(huì)被job執(zhí)行。

下面是refs策略的使用規(guī)則：

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

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

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

在下面這個(gè)例子中，job將只會(huì)執(zhí)行有tags的refs，或者通過API觸發(fā)器明確地請求構(gòu)建。

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

倉庫路徑只能用于父級倉庫執(zhí)行jobs，而不是forks：

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

上面這個(gè)例子將會(huì)為所有的分支執(zhí)行job，但master分支除外。

Job variables

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

當(dāng)設(shè)置了job級別的關(guān)鍵字variables，它會(huì)覆蓋全局YAML和預(yù)定義中的job變量。想要關(guān)閉全局變量可以在job中設(shè)置一個(gè)空數(shù)組：

job_name:
  variables: []

Job變量的優(yōu)先級關(guān)系可查看variables文檔說明。

tags

tags可以從允許運(yùn)行此項(xiàng)目的所有Runners中選擇特定的Runners來執(zhí)行jobs。

在注冊Runner的過程中，我們可以設(shè)置Runner的標(biāo)簽，比如ruby，postgres，development。

tags可通過tags來指定特殊的Runners來運(yùn)行jobs：

job:
  tags:
    - ruby
    - postgres

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

allow_failure

allow_failure可以用于當(dāng)你想設(shè)置一個(gè)job失敗的之后并不影響后續(xù)的CI組件的時(shí)候。失敗的jobs不會(huì)影響到commit狀態(tài)。

當(dāng)開啟了允許job失敗，所有的intents和purposes里的pipeline都是成功/綠色，但是也會(huì)有一個(gè)"CI build passed with warnings"信息顯示在merge request或commit或job page。這被允許失敗的作業(yè)使用，但是如果失敗表示其他地方應(yīng)采取其他（手動(dòng)）步驟。

下面的這個(gè)例子中，job1和job2將會(huì)并列進(jìn)行，如果job1失敗了，它也不會(huì)影響進(jìn)行中的下一個(gè)stage，因?yàn)檫@里有設(shè)置了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可以設(shè)置以下值：

1. on_success - 只有前面stages的所有工作成功時(shí)才執(zhí)行。 這是默認(rèn)值。
2. on_failure - 當(dāng)前面stages中任意一個(gè)jobs失敗后執(zhí)行。
3. always - 無論前面stages中jobs狀態(tài)如何都執(zhí)行。
4. ``manual - 手動(dòng)執(zhí)行(GitLab8.10增加)。更多請查看手動(dòng)操作。

舉個(gè)例子：

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. 只有當(dāng)build_job失敗的時(shí)候才會(huì)執(zhí)行``cleanup_build_job` 。
2. 不管前一個(gè)job執(zhí)行失敗還是成功都會(huì)執(zhí)行``cleanup_job` 。
3. 可以從GitLab界面中手動(dòng)執(zhí)行deploy_jobs。

Manual actions

GitLab 8.10 開始引入手動(dòng)執(zhí)行。GitLab 9.0 開始引入手動(dòng)停止。GitLab 9.2 開始引入保護(hù)手動(dòng)操作。

手動(dòng)操作指令是不自動(dòng)執(zhí)行的特殊類型的job；它們必須要人為啟動(dòng)。手動(dòng)操作指令可以從pipeline，build，environment和deployment視圖中啟動(dòng)。

部署到生產(chǎn)環(huán)境是手動(dòng)操作指令的一個(gè)很好示例。

了解更多請查看environments documentation。

手動(dòng)操作指令可以是可選的或阻塞。在定義了手動(dòng)執(zhí)行的那個(gè)stage中，手動(dòng)操作指令將會(huì)停止pipline中的自動(dòng)執(zhí)行指令。當(dāng)有人通過點(diǎn)擊play按鈕來執(zhí)行需要手動(dòng)執(zhí)行的job時(shí)，可以來恢復(fù)pipeline的執(zhí)行。

當(dāng)pipeline被阻塞時(shí)，即使是pipeline是成功狀態(tài)也不會(huì)merge。被阻塞的pipelines也有一個(gè)特殊的狀態(tài)，叫manual。

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

可選的手動(dòng)操作指令默認(rèn)設(shè)置allow_failure:true。

可選動(dòng)作的狀態(tài)不影響整個(gè)pipeline的狀態(tài)。

手動(dòng)操作指令被認(rèn)為是寫操作，所以當(dāng)前用戶觸發(fā)操作時(shí)，必須擁有操作保護(hù)分支的權(quán)限。換句話說，為了觸發(fā)一個(gè)手動(dòng)操作指令到pipeline中正在運(yùn)行的指定分支，當(dāng)前用戶必須擁有推送到這分支的權(quán)限。

enviroment

注意：

• GitLab 8.9 開始引入。
• 更多關(guān)于environment說明或者示例可以查看 documentation about environments。

environment用于定義job部署到特殊的環(huán)境中。如果指定了environment，并且沒有該名稱下的環(huán)境，則會(huì)自動(dòng)創(chuàng)建新環(huán)境。

在最簡單的格式中，環(huán)境關(guān)鍵字可以定義為：

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

在上面這個(gè)例子中，deploy to profuctionjob將會(huì)執(zhí)行部署到production環(huán)境的操作。

environment:name

注意

• GitLab 8.11 開始引入。
• 在GitLab8.11之前，環(huán)境名稱定義為environment:production。現(xiàn)在推薦的做法是定義為name關(guān)鍵字。

environment名稱可以包含：

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

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

除了在environment關(guān)鍵字右邊緊跟name定義方法外，也是可以為環(huán)境名稱單獨(dú)設(shè)定一個(gè)值。例如，用name關(guān)鍵字在environment下面設(shè)置：

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中添加。現(xiàn)在推薦的定義方法是在.gitlab-ci.yml。

這是設(shè)置一個(gè)可選值，它會(huì)顯示在按鈕中，點(diǎn)擊它可以帶你到設(shè)置的URL頁面。

在下面這個(gè)例子中，如果job都成功完成了，在environment/deployments頁面中將會(huì)創(chuàng)建一個(gè)合并請求的按鈕，它將指向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開始，當(dāng)在environment中定義了一個(gè)stop操作，GitLab將會(huì)在相關(guān)聯(lián)的分支本刪除時(shí)自動(dòng)觸發(fā)一個(gè)stop操作。

關(guān)閉(停止)environments可以通過在environment下定義關(guān)鍵字on_stop來實(shí)現(xiàn)。它定義了一個(gè)不同的job，用于關(guān)閉environment。

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

environment:action

Gitlab 8.13 開始引入。

action和on_stop聯(lián)合使用，定義在job中，用來關(guān)閉environment。

舉個(gè)例子：

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

上面這個(gè)例子中，我們定義了review_appjob來部署到review環(huán)境中，同時(shí)我們也定義了一個(gè)新stop_review_appjob在on_stop中。一旦review_appjob執(zhí)行完成并且成功，它將觸發(fā)定義在when中的stop_review_appjob。在這種情況下，我們設(shè)置為manual，需要通過GitLab's web界面來允許manual action。

stop_review_appjob需要定義下面這些關(guān)鍵字：

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

dynamic environment

注意：

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

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

舉個(gè)例子：

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

當(dāng)$CI_COMMIT_REF_NAME 被Runner設(shè)置為environment variable時(shí)，deply as review appjob將會(huì)被指定部署到動(dòng)態(tài)創(chuàng)建revuew/$CI_COMMIT_REF_NAME的環(huán)境中。$CI_ENVIRONMENT_SLUG變量是基于環(huán)境名稱的，最終組合成完整的URLs。在這種情況下，如果deploy as review appjob是運(yùn)行在名稱為pow的分支下，那么可以通過URLhttps"http://review-pw.example.com/來訪問這個(gè)環(huán)境。

這當(dāng)然意味著托管應(yīng)用程序的底層服務(wù)器已經(jīng)正確配置。

常見的做法是為分支創(chuàng)建動(dòng)態(tài)環(huán)境，并講它們作為Review Apps。可以通過https://gitlab.com/gitlab-exa...上查看使用Review Apps的簡單示例。

artifacts

注意：

• 非Windows平臺(tái)從GitLab Runner v0.7.0中引入。
• Windows平臺(tái)從GitLab Runner V1.0.0中引入。
• 在GItLab 9.2之前，在artifacts之后存儲(chǔ)緩存。
• 在GItLab 9.2之后，在artifacts之前存儲(chǔ)緩存。
• 目前并不是所有的executors都支持。
• 默認(rèn)情況下，job artifacts 只正對成功的jobs收集。

artifacts用于指定成功后應(yīng)附加到j(luò)ob的文件和目錄的列表。只能使用項(xiàng)目工作間內(nèi)的文件或目錄路徑。如果想要在不通的job之間傳遞artifacts，請查閱依賴關(guān)系。以下是一些例子：

發(fā)送binaries和.config中的所有文件：

artifacts:
  paths:
  - binaries/
  - .config

發(fā)送所有沒有被Git跟蹤的文件：

artifacts:
  untracked: true

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

artifacts:
  untracked: true
  paths:
  - binaries/

定義一個(gè)空的dependencies可以禁用artifact傳遞：

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

有時(shí)候只需要為標(biāo)簽為releases創(chuàng)建artifacts，以避免將臨時(shí)構(gòu)建的artifacts傳遞到生產(chǎn)服務(wù)器中。

只為tags創(chuàng)建artifacts（default-job將不會(huì)創(chuàng)建artifacts）：

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

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

在job成功完成后artifacts將會(huì)發(fā)送到GitLab中，同時(shí)也會(huì)在GitLab UI中提供下載。

artifacts:name

GitLab 8.6 和 Runner v1.1.0 引入。

name允許定義創(chuàng)建的artifacts存檔的名稱。這樣一來，我們可以為每個(gè)存檔提供一個(gè)唯一的名稱，當(dāng)需要從GitLab中下載是才不會(huì)混亂。artifacts:name可以使用任何的預(yù)定義變量(predefined variables)。它的默認(rèn)名稱為artifacts，當(dāng)下載是就變成了artifacts.zip。

配置示例

通過使用當(dāng)前job的名字作為存檔名稱：

job:
  artifacts:
    name: "$CI_JOB_NAME"

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

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

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

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

使用當(dāng)前stage和分支名稱作為存檔名稱：

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

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

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

artifacts:when

GitLab 8.9和GitLab Runner v1.3.0 引入。

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

artifacts:when可以設(shè)置一下值：

1. on_success - 當(dāng)job成功的時(shí)候上傳artifacts。默認(rèn)值。
2. on_failure - 當(dāng)job失敗的時(shí)候上傳artifacts。
3. always - 不論job失敗還是成功都上傳artifacts。

示例配置

只在job失敗的時(shí)候上傳artifacts。

job:
  artifacts:
    when: on_failure

artifacts:expire_in

GitLab 8.9 和 GitLab Runner v1.3.0 引入。

artifacts:expire_in用于過期后刪除郵件上傳的artifacts。默認(rèn)情況下，artifacts都是在GitLab中永久保存。expire_in允許設(shè)置設(shè)置artifacts的存儲(chǔ)時(shí)間，從它們被上傳存儲(chǔ)到GitLab開始計(jì)算。

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

過期后，artifacts會(huì)被通過一個(gè)默認(rèn)每小時(shí)執(zhí)行一次的定時(shí)job刪除，所以在過期后無法訪問artifacts。

expire_in是一個(gè)時(shí)間區(qū)間。下面可設(shè)置的值：

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

示例配置

設(shè)置artifacts的有效期為一個(gè)星期：

job:
  artifacts:
    expire_in: 1 week

dependencies

GitLab 8.6 和 GitLab RUnner v1.1.1引入。

這個(gè)功能應(yīng)該與artifacts一起使用，并允許定義在不同jobs之間傳遞artifacts。

注意：所有之前的stages都是默認(rèn)設(shè)置通過。

如果要使用此功能，應(yīng)該在上下文的job中定義dependencies，并且列出之前都已經(jīng)通過的jobs和可下載的artifacts。你只能在當(dāng)前執(zhí)行的stages前定義jobs。你如果在當(dāng)前stages或者后續(xù)的stages中定義了jobs，它將會(huì)報(bào)錯(cuò)。可以通過定義一個(gè)空數(shù)組是當(dāng)前job跳過下載artifacts。

在接下來的例子中，我們定義兩個(gè)帶artifacts的jobs，build:osx和build:linux。當(dāng)test:osx開始執(zhí)行的時(shí)候，build:osx的artifacts就會(huì)開始下載并且會(huì)在build的stages下執(zhí)行。同樣的會(huì)發(fā)生在test:linux，從build:linux中下載artifacts。

因?yàn)閟tages的優(yōu)先級關(guān)系，deployjob將會(huì)下載之前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

它可能會(huì)覆蓋全局定義的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允許你配置代碼覆蓋率將會(huì)從該job中提取輸出。

在這里正則表達(dá)式是唯一有效的值。因此，字符串的前后必須使用/包含來表明一個(gè)正確的正則表達(dá)式規(guī)則。特殊字符串需要轉(zhuǎn)義。

一個(gè)簡單的例子：

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

Git Strategy

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

你可以通過設(shè)置GIT_STRATEGY用于獲取最新的代碼，可以再全局variables或者是在單個(gè)job的variables模塊中設(shè)置。如果沒有設(shè)置，將從項(xiàng)目中使用默認(rèn)值。

可以設(shè)置的值有：clone，fetch，和none。

clone是最慢的選項(xiàng)。它會(huì)從頭開始克隆整個(gè)倉庫，包含每一個(gè)job，以確保項(xiàng)目工作區(qū)是最原始的。

variables:
  GIT_STRATEGY: clone

當(dāng)它重新使用項(xiàng)目工作區(qū)是，fetch是更快（如果不存在則返回克隆）。git clean用于撤銷上一個(gè)job做的任何改變，git fetch用于獲取上一個(gè)job到現(xiàn)在的的commit。

variables:
  GIT_STRATEGY: fetch

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

variables:
  GIT_STRATEGY: none

Git Checout

GitLab Runner 9.3 引入。

當(dāng)GIT_STRATEGY設(shè)置為clone或fetch時(shí)，可以使用GIT_CHECKOUT變量來指定是否應(yīng)該運(yùn)行git checkout。如果沒有指定，它默認(rèn)為true。就像GIT_STRATEGY一樣，它可以設(shè)置在全局variables或者是單個(gè)job的variables中設(shè)置。

如果設(shè)置為false，Runner就會(huì)：

• fetch - 更新倉庫并在當(dāng)前版本中保留工作副本，
• clone - 克隆倉庫并在默認(rèn)分支中保留工作副本。

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:

【如果設(shè)置這個(gè)為true將意味著clone和fetch策略都會(huì)讓Runner執(zhí)行項(xiàng)目工作區(qū)更新到最新：】

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變量用于在構(gòu)建之前拉取代碼時(shí)，Git子模塊是否或者如何被引入。就像GIT_STRATEGY一樣，它可在全局variables或者是單個(gè)job的variables模塊中設(shè)置。

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

• none意味著在拉取項(xiàng)目代碼時(shí)，子模塊將不會(huì)被引入。這個(gè)是默認(rèn)值，與v1.10之前相同的。
• normal意味著在只有頂級子模塊會(huì)被引入。它相當(dāng)于：

git submodule sync
git submodule update --init

recursive意味著所有的子模塊（包括子模塊的子模塊）都會(huì)被引入，他相當(dāng)于：

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

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

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

Job stages attempts

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

正在執(zhí)行的job將會(huì)按照你設(shè)置嘗試次數(shù)依次執(zhí)行下面的stages：

默認(rèn)是一次嘗試。

例如：

variables:
  GET_SOURCES_ATTEMPTS: 3

你可以在全局variables模塊中設(shè)置，也可以在單個(gè)job的variables模塊中設(shè)置。

Shallow cloning

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

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

注意：如果設(shè)置depth=1，并且有一個(gè)jobs隊(duì)列或者是重試jobs，則jobs可能會(huì)失敗。

由于Git抓取和克隆是基于一個(gè)REF，例如分支的名稱，所以Runner不能指定克隆一個(gè)commit SHA。如果隊(duì)列中有多個(gè)jobs，或者您正在重試舊的job，則需要測試的提交應(yīng)該在克隆的Git歷史記錄中存在。設(shè)置GIT_DEPTH太小的值可能會(huì)導(dǎo)致無法運(yùn)行哪些舊的commits。在job日志中可以查看unresolved reference。你應(yīng)該考慮設(shè)置GIT_DEPTH為一個(gè)更大的值。

當(dāng)GIT_DEPTH只設(shè)置了部分存在的記錄時(shí)，哪些依賴于git describe的jobs也許不能正確的工作。

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

variables:
  GIT_DEPTH: "3"

Hidden keys

GitLab 8.6 和 GitLab Runner v1.1.1引入。

Key 是以.開始的，GitLab CI 將不會(huì)處理它。你可以使用這個(gè)功能來忽略jobs，或者用Special YAML features 轉(zhuǎn)換隱藏鍵為模版。

在下面這個(gè)例子中，.key_name將會(huì)被忽略：

.key_name:
  script:
    - rake spec

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

Special YAML features

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

查看更多YAML features。

Anchors

GitLab 8.6 和 GitLab Runner v1.1.1引入。

YAML有個(gè)方便的功能稱為"錨",它可以讓你輕松的在文檔中復(fù)制內(nèi)容。Anchors可用于復(fù)制/繼承屬性，并且是使用hidden keys來提供模版的完美示例。

下面這個(gè)例子使用了anchors和map merging。它將會(huì)創(chuàng)建兩個(gè)jobs，test1和test2，該jobs將集成.job_template的參數(shù)，每個(gè)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)前設(shè)置，<<表示"merge the given hash into the current one"，*包括命名的anchor(job_definition)。擴(kuò)展版本如下：

.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

讓我們來看另外一個(gè)例子。這一次我們將用anchors來定義兩個(gè)服務(wù)。兩個(gè)服務(wù)會(huì)創(chuàng)建兩個(gè)job，test:postgres和test:mysql，他們會(huì)在.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

擴(kuò)展版本如下：

.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 可用于強(qiáng)制使用API調(diào)用重建特定分支，tag或commits。

在triggers文檔中查看更多。

pages

pages是一個(gè)特殊的job，用于將靜態(tài)的內(nèi)容上傳到GitLab，可用于為您的網(wǎng)站提供服務(wù)。它有特殊的語法，因此必須滿足以下兩個(gè)要求：

1. 任何靜態(tài)內(nèi)容必須放在public/目錄下
2. artifacts必須定義在public/目錄下

下面的這個(gè)例子是將所有文件從項(xiàng)目根目錄移動(dòng)到public/目錄。.public工作流是cp，并且它不會(huì)循環(huán)復(fù)制public/本身。

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

更多內(nèi)容請查看GitLab Pages用戶文檔。

Validate the .gitlab-ci.yml

GitLab CI的每個(gè)實(shí)例都有一個(gè)名為Lint的嵌入式調(diào)試工具。 你可以在gitlab實(shí)例的/ci/lint下找到該鏈接。

Skipping jobs

如果你的commit信息中包含[ci skip]或者[skip ci]，不論大小寫，那么這個(gè)commit將會(huì)創(chuàng)建但是jobs也會(huì)跳過。

Examples

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

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