Gitlab CI yaml官方配置文件翻譯

經過 .gitlab-ci.yml配置任務

git倉庫： https://github.com/Fennay/git...

此文檔用於描述.gitlab-ci.yml語法，.gitlab-ci.yml文件被用來管理項目的runner 任務。
若是想要快速的瞭解GitLab CI ，可查看快速引導。

.gitlab-ci.yml

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

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

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

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

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

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

用下面這個例子來講明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以後。它能夠是一個數組或者是多行字符串。

after_script

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

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。

緩存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-exa... Apps的簡單示例。

artifacts

注意：

• 非Windows平臺從GitLab Runner v0.7.0中引入。
• Windows平臺從GitLab Runner V1.0.0中引入。
• 在GItLab 9.2以前，在artifacts以後存儲緩存。
• 在GItLab 9.2以後，在artifacts以前存儲緩存。
• 目前並非全部的executors都支持。
• 默認狀況下，job artifacts 只正對成功的jobs收集。

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...