# GitLab CI/CD pipeline configuration reference > 原文：[https://docs.gitlab.com/ee/ci/yaml/README.html](https://docs.gitlab.com/ee/ci/yaml/README.html) * [Introduction](#introduction) * [Validate the `.gitlab-ci.yml`](#validate-the-gitlab-ciyml) * [Unavailable names for jobs](#unavailable-names-for-jobs) * [Using reserved keywords](#using-reserved-keywords) * [Configuration parameters](#configuration-parameters) * [Global parameters](#global-parameters) * [Global defaults](#global-defaults) * [`inherit`](#inherit) * [`stages`](#stages) * [`workflow:rules`](#workflowrules) * [`workflow:rules` templates](#workflowrules-templates) * [`include`](#include) * [`include:local`](#includelocal) * [`include:file`](#includefile) * [`include:remote`](#includeremote) * [`include:template`](#includetemplate) * [Nested includes](#nested-includes) * [Additional `includes` examples](#additional-includes-examples) * [Parameter details](#parameter-details) * [`image`](#image) * [`image:name`](#imagename) * [`image:entrypoint`](#imageentrypoint) * [`services`](#services) * [`services:name`](#servicesname) * [`services:alias`](#servicesalias) * [`services:entrypoint`](#servicesentrypoint) * [`services:command`](#servicescommand) * [`script`](#script) * [`before_script` and `after_script`](#before_script-and-after_script) * [Coloring script output](#coloring-script-output) * [Multiline commands](#multiline-commands) * [`stage`](#stage) * [Using your own Runners](#using-your-own-runners) * [`.pre` and `.post`](#pre-and-post) * [`extends`](#extends) * [Merge details](#merge-details) * [Using `extends` and `include` together](#using-extends-and-include-together) * [`rules`](#rules) * [Rules attributes](#rules-attributes) * [Rules clauses](#rules-clauses) * [Differences between `rules` and `only`/`except`](#differences-between-rules-and-onlyexcept) * [`rules:if`](#rulesif) * [`rules:changes`](#ruleschanges) * [`rules:exists`](#rulesexists) * [`rules:allow_failure`](#rulesallow_failure) * [Complex rule clauses](#complex-rule-clauses) * [`only`/`except` (basic)](#onlyexcept-basic) * [Regular expressions](#regular-expressions) * [Supported `only`/`except` regexp syntax](#supported-onlyexcept-regexp-syntax) * [`only`/`except` (advanced)](#onlyexcept-advanced) * [`only:refs`/`except:refs`](#onlyrefsexceptrefs) * [`only:kubernetes`/`except:kubernetes`](#onlykubernetesexceptkubernetes) * [`only:variables`/`except:variables`](#onlyvariablesexceptvariables) * [`only:changes`/`except:changes`](#onlychangesexceptchanges) * [Using `only:changes` with pipelines for merge requests](#using-onlychanges-with-pipelines-for-merge-requests) * [Using `only:changes` without pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests) * [Using `only:changes` with scheduled pipelines](#using-onlychanges-with-scheduled-pipelines) * [`needs`](#needs) * [Requirements and limitations](#requirements-and-limitations) * [Changing the `needs:` job limit](#changing-the-needs-job-limit) * [Artifact downloads with `needs`](#artifact-downloads-with-needs) * [Cross project artifact downloads with `needs`](#cross-project-artifact-downloads-with-needs-premium) * [Artifact downloads between pipelines in the same project](#artifact-downloads-between-pipelines-in-the-same-project) * [`tags`](#tags) * [`allow_failure`](#allow_failure) * [`when`](#when) * [`when:manual`](#whenmanual) * [Protecting manual jobs](#protecting-manual-jobs-premium) * [`when:delayed`](#whendelayed) * [`environment`](#environment) * [`environment:name`](#environmentname) * [`environment:url`](#environmenturl) * [`environment:on_stop`](#environmenton_stop) * [`environment:action`](#environmentaction) * [`environment:auto_stop_in`](#environmentauto_stop_in) * [`environment:kubernetes`](#environmentkubernetes) * [Dynamic environments](#dynamic-environments) * [`cache`](#cache) * [`cache:paths`](#cachepaths) * [`cache:key`](#cachekey) * [`cache:key:files`](#cachekeyfiles) * [`cache:key:prefix`](#cachekeyprefix) * [`cache:untracked`](#cacheuntracked) * [`cache:policy`](#cachepolicy) * [`artifacts`](#artifacts) * [`artifacts:paths`](#artifactspaths) * [`artifacts:exclude`](#artifactsexclude) * [`artifacts:expose_as`](#artifactsexpose_as) * [`artifacts:name`](#artifactsname) * [`artifacts:untracked`](#artifactsuntracked) * [`artifacts:when`](#artifactswhen) * [`artifacts:expire_in`](#artifactsexpire_in) * [`artifacts:reports`](#artifactsreports) * [`dependencies`](#dependencies) * [When a dependent job will fail](#when-a-dependent-job-will-fail) * [`coverage`](#coverage) * [`retry`](#retry) * [`timeout`](#timeout) * [`parallel`](#parallel) * [`trigger`](#trigger) * [Simple `trigger` syntax for multi-project pipelines](#simple-trigger-syntax-for-multi-project-pipelines) * [Complex `trigger` syntax for multi-project pipelines](#complex-trigger-syntax-for-multi-project-pipelines) * [`trigger` syntax for child pipeline](#trigger-syntax-for-child-pipeline) * [Trigger child pipeline with generated configuration file](#trigger-child-pipeline-with-generated-configuration-file) * [Linking pipelines with `trigger:strategy`](#linking-pipelines-with-triggerstrategy) * [Trigger a pipeline by API call](#trigger-a-pipeline-by-api-call) * [`interruptible`](#interruptible) * [`resource_group`](#resource_group) * [`release`](#release) * [`release-cli` Docker image](#release-cli-docker-image) * [Script](#script-1) * [`release:tag_name`](#releasetag_name) * [`release:name`](#releasename) * [`release:description`](#releasedescription) * [`release:ref`](#releaseref) * [`release:milestones`](#releasemilestones) * [`release:released_at`](#releasereleased_at) * [Complete example for `release`](#complete-example-for-release) * [`releaser-cli` command line](#releaser-cli-command-line) * [`pages`](#pages) * [`variables`](#variables) * [Git strategy](#git-strategy) * [Git submodule strategy](#git-submodule-strategy) * [Git checkout](#git-checkout) * [Git clean flags](#git-clean-flags) * [Git fetch extra flags](#git-fetch-extra-flags) * [Job stages attempts](#job-stages-attempts) * [Shallow cloning](#shallow-cloning) * [Custom build directories](#custom-build-directories) * [Handling concurrency](#handling-concurrency) * [Nested paths](#nested-paths) * [Special YAML features](#special-yaml-features) * [Anchors](#anchors) * [YAML anchors for `before_script` and `after_script`](#yaml-anchors-for-before_script-and-after_script) * [YAML anchors for `script`](#yaml-anchors-for-script) * [YAML anchors for variables](#yaml-anchors-for-variables) * [Hide jobs](#hide-jobs) * [Skip Pipeline](#skip-pipeline) * [Processing Git pushes](#processing-git-pushes) * [Deprecated parameters](#deprecated-parameters) * [Globally-defined `types`](#globally-defined-types) * [Job-defined `type`](#job-defined-type) * [Globally-defined `image`, `services`, `cache`, `before_script`, `after_script`](#globally-defined-image-services-cache-before_script-after_script) # GitLab CI/CD pipeline configuration reference[](#gitlab-cicd-pipeline-configuration-reference "Permalink") 在每個項目中，使用名為`.gitlab-ci.yml`的 YAML 文件配置 GitLab CI / CD [管道](../pipelines/index.html) . `.gitlab-ci.yml`文件定義管道的結構和順序，并確定： * 使用[GitLab Runner](https://docs.gitlab.com/runner/)執行什么. * 遇到特定條件時要做出什么決定. 例如，當一個過程成功或失敗時. 本主題涵蓋 CI / CD 管道配置. 有關其他 CI / CD 配置信息，請參閱： * [GitLab CI / CD 變量](../variables/README.html) ，用于配置運行管道的環境. * [GitLab Runner 高級配置](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) ，用于配置 GitLab Runner. 我們有配置管道的完整示例： * 有關 GitLab CI / CD 的快速介紹，請遵循我們的[快速入門指南](../quick_start/README.html) . * 有關示例集合，請參見[GitLab CI / CD 示例](../examples/README.html) . * 要看到一個大`.gitlab-ci.yml`在企業使用的文件，看到[`.gitlab-ci.yml`文件`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml) . > 有關 GitLab CI / CD 的其他信息： > > * 觀看[CI / CD 輕松配置](https://www.youtube.com/embed/opdLqwz6tcE)視頻. > * [在組織的](https://about.gitlab.com/compare/github-actions-alternative/)網絡廣播中觀看" [為 CI / CD](https://about.gitlab.com/compare/github-actions-alternative/)辯護"，以了解 CI / CD 的好處以及如何衡量 CI / CD 自動化的結果. > * 了解[Verizon](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/)如何使用 GitLab [將重建工作](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/)從 30 天[減少](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/)到 8 小時以下. **注意：**如果您有[從 GitLab 提取鏡像的存儲庫](../../user/project/repository/repository_mirroring.html#pulling-from-a-remote-repository-starter) ，則可能需要在項目的**"設置">"存儲庫">"從遠程存儲庫中提取">"觸發管道更新鏡像"中**啟用管道觸發. ## Introduction[](#introduction "Permalink") 管道配置從作業開始. 作業是`.gitlab-ci.yml`文件的最基本元素. 工作是： * 定義了約束，指出應在什么條件下執行它們. * 具有任意名稱的頂級元素，并且必須至少包含[`script`](#script)子句. * 不限制可以定義多少個. 例如： ``` job1: script: "execute-script-for-job1" job2: script: "execute-script-for-job2" ``` 上面的示例是具有兩個單獨作業的最簡單的 CI / CD 配置，其中每個作業執行一個不同的命令. 當然，命令可以直接執行代碼（ `./configure;make;make install` ）或在存儲庫中運行腳本（ `test.sh` ）. 喬布斯被拾起[運動員](../runners/README.html)和跑步者的環境中執行. 重要的是，每個作業彼此獨立運行. ### Validate the `.gitlab-ci.yml`[](#validate-the-gitlab-ciyml "Permalink") GitLab CI / CD 的每個實例都有一個稱為 Lint 的嵌入式調試工具，該工具可以驗證`.gitlab-ci.yml`文件的內容. 您可以在項目名稱空間的`ci/lint`頁下找到 Lint. 例如， `https://gitlab.example.com/gitlab-org/project-123/-/ci/lint` . ### Unavailable names for jobs[](#unavailable-names-for-jobs "Permalink") 每個作業必須具有唯一的名稱，但是有一些**保留的`keywords`不能用作作業名稱** ： * `image` * `services` * `stages` * `types` * `before_script` * `after_script` * `variables` * `cache` * `include` ### Using reserved keywords[](#using-reserved-keywords "Permalink") 如果在使用特定值（例如`true`或`false` ）時收到驗證錯誤，請嘗試執行以下操作： * 引用他們. * 將它們更改為其他形式. 例如， `/bin/true` . ## Configuration parameters[](#configuration-parameters "Permalink") 作業定義為定義作業行為的參數列表. 下表列出了作業的可用參數： | Keyword | Description | | --- | --- | | [`script`](#script) | 由 Runner 執行的 Shell 腳本. | | [`image`](#image) | 使用 Docker 映像 也可用： `image:name`和`image:entrypoint` . | | [`services`](#services) | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. | | [`before_script`](#before_script-and-after_script) | 覆蓋作業之前執行的一組命令. | | [`after_script`](#before_script-and-after_script) | 覆蓋作業后執行的一組命令. | | [`stage`](#stage) | 定義一個工作階段（默認： `test` ）. | | [`only`](#onlyexcept-basic) | 限制創建作業的時間. 也可用： [`only:refs` ， `only:kubernetes` ， `only:variables`和`only:changes`](#onlyexcept-advanced) . | | [`except`](#onlyexcept-basic) | 限制未創建作業的時間. 也可用： [`except:refs` ， `except:kubernetes` ， `except:variables`和`except:changes`](#onlyexcept-advanced) . | | [`rules`](#rules) | 評估和確定作業的選定屬性以及是否創建作業的條件列表. 不能`only`與/ `except`一起使用. | | [`tags`](#tags) | 用于選擇 Runner 的標簽列表. | | [`allow_failure`](#allow_failure) | 允許作業失敗. 失敗的作業不會影響提交狀態. | | [`when`](#when) | 什么時候開始工作. 也可用： `when:manual`和`when:delayed` . | | [`environment`](#environment) | 作業部署到的環境的名稱. 也可用： `environment:name` ， `environment:url` ， `environment:on_stop` ， `environment:auto_stop_in`和`environment:action` . | | [`cache`](#cache) | 在后續運行之間應緩存的文件列表. 也可用： `cache:paths` ， `cache:key` ， `cache:untracked`和`cache:policy` . | | [`artifacts`](#artifacts) | 成功時附加到作業的文件和目錄列表. 也可以使用： `artifacts:paths` ， `artifacts:exclude` ， `artifacts:expose_as` ， `artifacts:name` ， `artifacts:untracked` ， `artifacts:when` ， `artifacts:expire_in` ， `artifacts:reports` ， `artifacts:reports:junit` ， `artifacts:reports:cobertura`和`artifacts:reports:terraform` . 在 GitLab [企業版](https://about.gitlab.com/pricing/) ，這些都是可供選擇： `artifacts:reports:codequality` ， `artifacts:reports:sast` ， `artifacts:reports:dependency_scanning` ， `artifacts:reports:container_scanning` ， `artifacts:reports:dast` ， `artifacts:reports:license_scanning` ， `artifacts:reports:license_management` （已在 GitLab 13.0 中刪除）， `artifacts:reports:performance`和`artifacts:reports:metrics` . | | [`dependencies`](#dependencies) | 通過提供要從中獲取工件的作業列表，限制將哪些工件傳遞給特定作業. | | [`coverage`](#coverage) | 給定作業的代碼覆蓋率設置. | | [`retry`](#retry) | 發生故障時可以自動重試作業的時間和次數. | | [`timeout`](#timeout) | 定義優先于項目范圍設置的自定義作業級別超時. | | [`parallel`](#parallel) | 多少個作業實例應并行運行. | | [`trigger`](#trigger) | 定義下游管道觸發器. | | [`include`](#include) | 允許此作業包括外部 YAML 文件. 也可用： `include:local` ， `include:file` ， `include:template`和`include:remote` . | | [`extends`](#extends) | 該作業將要繼承的配置條目. | | [`pages`](#pages) | 上載作業結果以用于 GitLab 頁面. | | [`variables`](#variables) | 在作業級別上定義作業變量. | | [`interruptible`](#interruptible) | 定義在通過新的運行使其冗余時是否可以取消作業. | | [`resource_group`](#resource_group) | 限制作業并發. | | [`release`](#release) | 指示 Runner 生成[Release](../../user/project/releases/index.html)對象. | **Note:** Parameters `types` and `type` are [deprecated](#deprecated-parameters). ## Global parameters[](#global-parameters "Permalink") 必須在全局級別定義一些參數，這會影響管道中的所有作業. ### Global defaults[](#global-defaults "Permalink") 可以使用`default:`關鍵字將某些參數全局設置為所有作業的`default:` . 然后可以通過特定于作業的配置覆蓋默認參數. 可以在`default:`塊內定義以下作業參數： * [`image`](#image) * [`services`](#services) * [`before_script`](#before_script-and-after_script) * [`after_script`](#before_script-and-after_script) * [`tags`](#tags) * [`cache`](#cache) * [`artifacts`](#artifacts) * [`retry`](#retry) * [`timeout`](#timeout) * [`interruptible`](#interruptible) 在以下示例中，除了`rspec 2.6`作業（使用`ruby:2.6`圖像）以外，所有作業的默認設置都是`ruby:2.5`圖像： ``` default: image: ruby:2.5 rspec: script: bundle exec rspec rspec 2.6: image: ruby:2.6 script: bundle exec rspec ``` #### `inherit`[](#inherit "Permalink") 在 GitLab 12.9 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) . 您可以使用`inherit:`參數禁用對全局定義的默認值和變量的`inherit:` . 要啟用或禁用所有`variables:`或`default:`參數的繼承，請使用以下格式： * `default: true` or `default: false` * `variables: true` or `variables: false` 要僅繼承`default:`參數或`variables:`的子集，請指定要繼承的內容，未列出的任何內容均**不會**被繼承. 使用以下格式之一： ``` inherit: default: [parameter1, parameter2] variables: [VARIABLE1, VARIABLE2] ``` Or: ``` inherit: default: - parameter1 - parameter2 variables: - VARIABLE1 - VARIABLE2 ``` 在以下示例中： * `rubocop`: * **會**繼承：沒有. * `rspec`: * **將**繼承：默認`image`和`WEBHOOK_URL`變量. * **不會**繼承：默認的`before_script`和`DOMAIN`變量. * `capybara`: * **將**繼承：默認的`before_script`和`image` . * 將**不會**繼承： `DOMAIN`和`WEBHOOK_URL`變量. * `karma`: * **將**繼承：默認`image` ， `before_script`和`DOMAIN`變量. * will **not** inherit: `WEBHOOK_URL` variable. ``` default: image: 'ruby:2.4' before_script: - echo Hello World variables: DOMAIN: example.com WEBHOOK_URL: https://my-webhook.example.com rubocop: inherit: default: false variables: false script: bundle exec rubocop rspec: inherit: default: [image] variables: [WEBHOOK_URL] script: bundle exec rspec capybara: inherit: variables: false script: bundle exec capybara karma: inherit: default: true variables: [DOMAIN] script: karma ``` ### `stages`[](#stages "Permalink") `stages`用于定義包含作業的階段，并且為管道全局定義. 的規范`stages`允許具有靈活的多階段流水線. `stages`中元素的順序定義了作業執行的順序： 1. 同一階段的作業并行運行. 2. 前一階段的作業成功完成后，將運行下一階段的作業. 讓我們考慮以下示例，該示例定義了 3 個階段： ``` stages: - build - test - deploy ``` 1. 首先，所有`build`作業均并行執行. 2. 如果所有`build`作業均成功，則`test`作業將并行執行. 3. 如果所有`test`作業均成功，則將并行執行`deploy`作業. 4. 如果所有`deploy`作業均成功，則將提交標記為`passed` . 5. 如果先前的任何作業失敗，則將提交標記為`failed`并且不執行后續階段的作業. 還有兩個邊緣情況值得一提： 1. 如果`.gitlab-ci.yml`中未定義任何`stages` ，則默認允許將`build` ， `test`和`deploy`用作作業的階段. 2. 如果作業未指定`stage` ，則為該作業分配`test`階段. ### `workflow:rules`[](#workflowrules "Permalink") 在 GitLab 12.5 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) 頂級`workflow:`關鍵字適用于整個管道，并將確定是否創建管道. 當前，它接受一個`rules:`與[`rules:`](#rules)類似的鍵：在 job 中[定義](#rules) ，可動態配置管道. 如果您不熟悉 GitLab CI / CD 和`workflow: rules` ，則可能會發現[`workflow:rules`模板](#workflowrules-templates)很有用. 要定義自己的`workflow: rules` ，當前可用的配置選項為： * [`if`](#rulesif) ：定義規則. * [`when`](#when) ：可以設置為`always`或`never` . 如果未提供，則默認值`always` . 評估`if`規則的列表，直到匹配單個規則. 如果沒有比賽，最后`when`會被使用： ``` workflow: rules: - if: $CI_COMMIT_REF_NAME =~ /-wip$/ when: never - if: $CI_COMMIT_TAG when: never - when: always ``` #### `workflow:rules` templates[](#workflowrules-templates "Permalink") 在 GitLab 13.0 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) . 我們提供預制模板，供您用于設置`workflow: rules`管道使用`workflow: rules`常見方案的`workflow: rules` . 使用這些將使事情變得容易，并防止重復的管道運行. [`Branch-Pipelines`模板](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)使您的管道針對分支和標簽運行. 分支管道狀態將顯示在使用該分支作為源的合并請求中，但是此管道類型不支持" [合并請求管道"](../merge_request_pipelines/)提供的任何功能，例如["合并結果管道"](../merge_request_pipelines/#pipelines-for-merged-results-premium)或" [合并訓練"](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/) . 如果您有意避免使用這些功能，請使用此模板. 它[包括](#include)以下內容： ``` include: - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml' ``` The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml) makes your pipelines run for the default branch (usually `master`), tags, and all types of merge request pipelines. Use this template if you use any of the the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned above. 它[包括](#include)以下內容： ``` include: - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml' ``` ### `include`[](#include "Permalink") 版本歷史 * 在[GitLab Premium](https://about.gitlab.com/pricing/) 10.5 中引入. * 自 10.6 開始適用于 Starter，Premium 和 Ultimate. * 在 11.4 中[移至](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) GitLab Core. 使用`include`關鍵字允許包含外部 YAML 文件. 這有助于將 CI / CD 配置分解為多個文件，并提高了長配置文件的可讀性. 也可以將模板文件存儲在中央存儲庫中，并且項目包括其配置文件. 這有助于避免重復配置，例如，所有項目的全局默認變量. `include`要求外部 YAML 文件具有擴展名`.yml`或`.yaml` ，否則將不包含外部文件. `include`支持以下包含方法： | Method | Description | | --- | --- | | [`local`](#includelocal) | 包括來自本地項目存儲庫的文件. | | [`file`](#includefile) | 包括來自其他項目存儲庫的文件. | | [`remote`](#includeremote) | 包括來自遠程 URL 的文件. 必須公開可用. | | [`template`](#includetemplate) | 包括由 GitLab 提供的模板. | `include`方法不支持[變量擴展](../variables/where_variables_can_be_used.html#variables-usage) . **注意：**所有方法包含的`.gitlab-ci.yml`配置在創建管道時進行評估. 該配置是及時的快照，并保留在數據庫中. 在創建下一個管道之前，對引用的`.gitlab-ci.yml`配置的任何更改都不會反映在 GitLab 中. `include`定義的文件是： * 與`.gitlab-ci.yml`那些合并. * 無論`include`關鍵字的位置如何，始終首先評估并與`.gitlab-ci.yml`的內容合并. **提示：**使用合并功能可以自定義和覆蓋包含本地定義的 CI / CD 配置. `.gitlab-ci.yml`本地定義將覆蓋包含的定義.**注意：**不支持在`include`來源的不同 YAML 文件中使用[YAML 錨](#anchors) . 您只能引用同一文件中的錨. 除了使用 YAML 定位符，您還可以使用[`extends`關鍵字](#extends) . #### `include:local`[](#includelocal "Permalink") `include:local`包含與`.gitlab-ci.yml`位于同一存儲庫中的文件. 使用相對于根目錄（ `/` ）的完整路徑進行引用. 您只能在配置文件所在的同一分支上使用 Git 當前跟蹤的文件. 換句話說，使用`include:local` ，請確保`.gitlab-ci.yml`和本地文件都在同一分支上. 所有[嵌套的包含](#nested-includes)將在同一項目的范圍內執行，因此可以使用本地，項目，遠程或模板包含. **注意：**不支持通過 Git 子模塊路徑包含本地文件. Example: ``` include: - local: '/templates/.gitlab-ci-template.yml' ``` **Tip:** Local includes can be used as a replacement for symbolic links which are not followed. 可以將其定義為簡短的本地包含： ``` include: '.gitlab-ci-production.yml' ``` #### `include:file`[](#includefile "Permalink") 在 GitLab 11.7 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) . 要在同一 GitLab 實例下包含來自另一個私有項目的`include:file` ，請使用`include:file` . 使用相對于根目錄（ `/` ）的完整路徑引用該文件. 例如： ``` include: - project: 'my-group/my-project' file: '/templates/.gitlab-ci-template.yml' ``` 您還可以指定`ref` ，默認值為項目的`HEAD` ： ``` include: - project: 'my-group/my-project' ref: master file: '/templates/.gitlab-ci-template.yml' - project: 'my-group/my-project' ref: v1.0.0 file: '/templates/.gitlab-ci-template.yml' - project: 'my-group/my-project' ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA file: '/templates/.gitlab-ci-template.yml' ``` 所有[嵌套的包含](#nested-includes)將在目標項目的范圍內執行，因此可以使用本地（相對于目標項目），項目，遠程或模板包含. #### `include:remote`[](#includeremote "Permalink") `include:remote`可用于通過 HTTP / HTTPS 包含來自其他位置的文件，并使用完整 URL 進行引用. 遠程文件必須可以通過簡單的 GET 請求公開訪問，因為不支持遠程 URL 中的身份驗證模式. 例如： ``` include: - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' ``` 所有[嵌套的 include](#nested-includes)將在沒有上下文的情況下作為公共用戶執行，因此僅允許另一個遠程或公共項目或模板. #### `include:template`[](#includetemplate "Permalink") 在 GitLab 11.7 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53445) . `include:template`可用于包含[GitLab 隨附的](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates) `.gitlab-ci.yml`模板. 例如： ``` # File sourced from GitLab's template collection include: - template: Auto-DevOps.gitlab-ci.yml ``` Multiple `include:template` files: ``` include: - template: Android-Fastlane.gitlab-ci.yml - template: Auto-DevOps.gitlab-ci.yml ``` 所有[嵌套的包含](#nested-includes)將僅在用戶許可下執行，因此可以使用項目，遠程或模板包含. #### Nested includes[](#nested-includes "Permalink") 在 GitLab 11.9 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836) . 嵌套包含可讓您組成一組包含. 總共允許 100 個 include，但是重復的 include 被視為配置錯誤. 從[GitLab 12.4 開始](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) ，解析所有文件的時間限制為 30 秒. #### Additional `includes` examples[](#additional-includes-examples "Permalink") 有可用的[其他`includes`示例](includes.html)列表. ## Parameter details[](#parameter-details "Permalink") 以下是用于配置 CI / CD 管道的參數的詳細說明. ### `image`[](#image "Permalink") 用于指定要用于作業[的 Docker 映像](../docker/using_docker_images.html#what-is-an-image) . For: * Simple definition examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.html#define-image-and-services-from-gitlab-ciyml). * 詳細的使用信息，請參閱[Docker 集成](../docker/README.html)文檔. #### `image:name`[](#imagename "Permalink") An [extended Docker configuration option](../docker/using_docker_images.html#extended-docker-configuration-options). 有關更多信息，請參閱[`image`可用設置](../docker/using_docker_images.html#available-settings-for-image) . #### `image:entrypoint`[](#imageentrypoint "Permalink") An [extended Docker configuration option](../docker/using_docker_images.html#extended-docker-configuration-options). 有關更多信息，請參閱[`image`可用設置](../docker/using_docker_images.html#available-settings-for-image) . #### `services`[](#services "Permalink") 用于指定[服務 Docker 映像](../docker/using_docker_images.html#what-is-a-service) ，該映像鏈接到 image 中指定的基本[`image`](#image) . For: * 簡單的定義示例，請參閱[從`.gitlab-ci.yml`定義`image`和`services`](../docker/using_docker_images.html#define-image-and-services-from-gitlab-ciyml) . * 詳細的使用信息，請參閱[Docker 集成](../docker/README.html)文檔. * 有關示例服務，請參見[GitLab CI / CD 服務](../services/README.html) . ##### `services:name`[](#servicesname "Permalink") An [extended Docker configuration option](../docker/using_docker_images.html#extended-docker-configuration-options). For more information, see [Available settings for `services`](../docker/using_docker_images.html#available-settings-for-services). ##### `services:alias`[](#servicesalias "Permalink") An [extended Docker configuration option](../docker/using_docker_images.html#extended-docker-configuration-options). 有關更多信息，請參閱[`services`可用設置](../docker/using_docker_images.html#available-settings-for-services) . ##### `services:entrypoint`[](#servicesentrypoint "Permalink") An [extended Docker configuration option](../docker/using_docker_images.html#extended-docker-configuration-options). 有關更多信息，請參閱[`services`可用設置](../docker/using_docker_images.html#available-settings-for-services) . ##### `services:command`[](#servicescommand "Permalink") An [extended Docker configuration option](../docker/using_docker_images.html#extended-docker-configuration-options). 有關更多信息，請參閱[`services`可用設置](../docker/using_docker_images.html#available-settings-for-services) . ### `script`[](#script "Permalink") `script`是作業所需的唯一必需關鍵字. 這是一個由 Runner 執行的 shell 腳本. 例如： ``` job: script: "bundle exec rspec" ``` [腳本的 YAML 錨](#yaml-anchors-for-script)可用. 此參數還可以包含使用數組的多個命令： ``` job: script: - uname -a - bundle exec rspec ``` **注意：**有時， `script`命令將需要用單引號或雙引號引起來. 例如，包含冒號命令（ `:` ）需要加引號，以便被包裹的 YAML 解析器知道來解釋整個事情作為一個字符串，而不是一個"鍵：值"對. 使用特殊字符時要小心： `:` ， `{` ， `}` ， `[` ， `]` ， `,` ， `&` ， `*` ， `#` ， `?` ， `|` ， `-` ， `<` ， `>` ， `=` `!` ， `%` ， `@` ， ``` . 如果任何腳本命令返回的退出代碼都不為零，則該作業將失敗，并且其他命令將不再執行. 通過將退出代碼存儲在變量中，可以避免此行為： ``` job: script: - false || exit_code=$? - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi; ``` #### `before_script` and `after_script`[](#before_script-and-after_script "Permalink") 在 GitLab 8.7 中引入，需要 GitLab Runner v1.2. `before_script`用于定義一個命令，該命令應在每個作業（包括部署作業）之前，但在還原任何[工件之后運行](#artifacts) . 這必須是一個數組. `before_script`中指定的[`script`](#script)與主腳本中指定的任何腳本串聯在一起，并在單個 shell 中一起執行. `after_script`用于定義將在每個作業（包括失敗的作業）之后運行的命令. 這必須是一個數組. `after_script`中指定的腳本在新的 shell 中執行，與任何`before_script`或`script`腳本分開. 結果，他們： * 將當前工作目錄設置回默認目錄. * 無法訪問由`before_script`或`script`定義的腳本完成的更改，包括： * `script`腳本中導出的命令別名和變量. * 在工作樹之外進行更改（取決于 Runner 執行程序），例如`before_script`或`script`腳本安裝的軟件. * 有一個單獨的超時，硬編碼為 5 分鐘. 有關詳細信息，請參見[相關問題](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716) . * 不要影響作業的退出代碼. 如果`script`部分成功并且`after_script`超時或失敗，則該作業將以代碼`0` （ `Job Succeeded` ）退出. 如果按工作設置全局定義的`before_script`或`after_script`則有可能覆蓋它： ``` default: 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 ``` [YAML anchors for `before_script` and `after_script`](#yaml-anchors-for-before_script-and-after_script) are available. #### Coloring script output[](#coloring-script-output "Permalink") 腳本輸出可以使用[ANSI 轉義碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)或運行輸出 ANSI 轉義碼的命令或程序來著色. 例如，使用[帶有顏色代碼的 Bash](https://misc.flogisoft.com/bash/tip_colors_and_formatting) ： ``` job: script: - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again." ``` 您可以在 Shell 變量甚至[自定義環境變量中](../variables/README.html#custom-environment-variables)定義顏色代碼，這使命令更易于閱讀和重用. 例如，使用與上述相同的示例以及在`before_script`定義的變量： ``` job: before_script: - TXT_RED="\e[31m" && TXT_CLEAR="\e[0m" script: - echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again." - echo "This text is not colored" ``` 或使用[PowerShell 顏色代碼](https://superuser.com/a/1259916) ： ``` job: before_script: - $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m" script: - Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again." - Write-Host "This text is not colored" ``` #### Multiline commands[](#multiline-commands "Permalink") 您可以使用[`|`](https://yaml-multiline.info/)將長命令分成多行命令以提高可讀性[`|`](https://yaml-multiline.info/) [（文字）和`>` （折疊）YAML 多行塊標量指標](https://yaml-multiline.info/) . **警告：**如果將多個命令組合到一個命令字符串中，則只會報告最后一個命令的失敗或成功， [錯誤地忽略了由于 bug 導致的先前命令的失敗](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394) . 如果作業的成功取決于這些命令的成功或失敗，則可以將命令作為單獨的`script:`項目運行，或在需要時將`exit 1`命令添加到適當的命令字符串中. 您可以使用`|` （文字）YAML 多行塊標量指示器，用于在作業描述的`script`部分中的多行上編寫命令. 每行都被視為一個單獨的命令. 在作業日志中僅重復第一個命令，但仍執行其他命令： ``` job: script: - | echo "First command line." echo "Second command line." echo "Third command line." ``` 上面的示例在作業日志中呈現為： ``` $ echo First command line # collapsed multi-line command First command line Second command line. Third command line. ``` `>` （折疊的）YAML 多行塊標量指示符將節之間的空行視為新命令的開始： ``` job: script: - > echo "First command line is split over two lines." echo "Second command line." ``` 這與編寫不帶`>`或`|`多行命令的行為類似 塊標量指標： ``` job: script: - echo "First command line is split over two lines." echo "Second command line." ``` 上面的兩個示例在作業日志中均顯示為： ``` $ echo First command line is split over two lines. # collapsed multi-line command First command line is split over two lines. Second command line. ``` 當`>`或`|` 塊標量指示符被省略，GitLab 將通過連接非空行來形成命令，因此請確保在連接時行可以運行. [此處的](https://en.wikipedia.org/wiki/Here_document) Shell [文件可](https://en.wikipedia.org/wiki/Here_document)與`|` 和`>`運算符. 下面的示例將小寫字母音譯為大寫字母： ``` job: script: - | tr a-z A-Z << END_TEXT one two three four five six END_TEXT ``` 結果是： ``` $ tr a-z A-Z << END_TEXT # collapsed multi-line command ONE TWO THREE FOUR FIVE SIX ``` ### `stage`[](#stage "Permalink") `stage`是按職位定義的，并且依賴于全局定義的[`stages`](#stages) . 它允許將作業分為不同的階段，并且同一`stage`作業可以并行執行（取決于[特定條件](#using-your-own-runners) ）. 例如： ``` stages: - build - test - deploy job 0: stage: .pre script: make something useful before build stage job 1: stage: build script: make build dependencies job 2: stage: build script: make build artifacts job 3: stage: test script: make test job 4: stage: deploy script: make deploy job 5: stage: .post script: make something useful at the end of pipeline ``` #### Using your own Runners[](#using-your-own-runners "Permalink") 使用自己的 Runners 時，默認情況下，GitLab Runner 一次僅運行一個作業（有關更多信息，請參見[Runner 全局設置中](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)的`concurrent`標志）. 僅在以下情況下，作業將在您自己的跑步者上并行運行： * Run on different Runners. * 跑步者的`concurrent`設置已更改. #### `.pre` and `.post`[](#pre-and-post "Permalink") 在 GitLab 12.4 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) . 每個管道均可使用以下階段： * `.pre` ，它始終是管道中的第一階段. * `.post` ，它始終是管道中的最后一個階段. 用戶定義的階段在`.pre`之后和`.post`之前執行. 即使`.gitlab-ci.yml`定義不正確， `.pre`和`.post`的順序也無法更改. 例如，以下是等效配置： * 按順序配置： ``` stages: - .pre - a - b - .post ``` * 配置亂序： ``` stages: - a - .pre - b - .post ``` * 未明確配置： ``` stages: - a - b ``` **Note:** A pipeline won’t be created if it only contains jobs in `.pre` or `.post` stages. ### `extends`[](#extends "Permalink") 在 GitLab 11.3 中引入. `extends`定義使用`extends`的作業將要繼承的條目名稱. 它是使用[YAML 錨點](#anchors)的替代方法，并且更具靈活性和可讀性： ``` .tests: script: rake test stage: test only: refs: - branches rspec: extends: .tests script: rake rspec only: variables: - $RSPEC ``` 在上面的示例中， `rspec`作業繼承自`.tests`模板作業. GitLab 將基于密鑰執行反向深度合并. GitLab 將： * Merge the `rspec` contents into `.tests` recursively. * 不合并鍵的值. 這將導致以下`rspec`作業： ``` rspec: script: rake rspec stage: test only: refs: - branches variables: - $RSPEC ``` **注意：**請注意， `script: rake test`已被`script: rake rspec`覆蓋. 如果您確實希望包含`rake test` ，請參見[`before_script`和`after_script`](#before_script-and-after_script) . 在此示例中， `.tests`是[隱藏作業](#hide-jobs) ，但是也可以從常規作業繼承. `extends`支持多級繼承，但是不建議使用三個以上級別. 支持的最大嵌套級別為 10.以下示例具有兩個繼承級別： ``` .tests: only: - pushes .rspec: extends: .tests script: rake rspec rspec 1: variables: RSPEC_SUITE: '1' extends: .rspec rspec 2: variables: RSPEC_SUITE: '2' extends: .rspec spinach: extends: .tests script: rake spinach ``` 在 GitLab 12.0 和更高版本中，還可以使用多個父對象進行`extends` . #### Merge details[](#merge-details "Permalink") `extends`可以合并哈希，但不能合并數組. 用于合并的算法是"最近的范圍獲勝"，因此來自最后一個成員的鍵將始終覆蓋在其他級別定義的任何內容. 例如： ``` .only-important: variables: URL: "http://my-url.internal" IMPORTANT_VAR: "the details" only: - master - stable tags: - production script: - echo "Hello world!" .in-docker: variables: URL: "http://docker-url.internal" tags: - docker image: alpine rspec: variables: GITLAB: "is-awesome" extends: - .only-important - .in-docker script: - rake rspec ``` 這將導致以下`rspec`作業： ``` rspec: variables: URL: "http://docker-url.internal" IMPORTANT_VAR: "the details" GITLAB: "is-awesome" only: - master - stable tags: - docker image: alpine script: - rake rspec ``` 請注意，在上面的示例中： * `variables`部分已合并，但`URL: "http://my-url.internal"`已被`URL: "http://docker-url.internal"`覆蓋. * `tags: ['production']`已被`tags: ['docker']`覆蓋. * `script`尚未合并，而是`script: ['echo "Hello world!"']`被`script: ['rake rspec']`覆蓋. 可以使用[YAML 錨點](#anchors)合并數組. #### Using `extends` and `include` together[](#using-extends-and-include-together "Permalink") `extends`配置文件`extends`到`include`配置文件. 例如，如果您有本地`included.yml`文件： ``` .template: script: - echo Hello! ``` 然后，在`.gitlab-ci.yml`您可以像這樣使用它： ``` include: included.yml useTemplate: image: alpine extends: .template ``` 這將運行一個名為`useTemplate`的作業，該作業運行`echo Hello!` 如`.template`作業中所定義，并使用本地作業中所定義的`alpine` Docker 映像. ### `rules`[](#rules "Permalink") 在 GitLab 12.3 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) . `rules`關鍵字是一種設置作業策略的方法，該策略確定是否將作業添加到管道. 將按*順序*評估單個規則子句的列表，直到一個匹配. 匹配后，根據配置將作業包括在管道中或從管道中排除. 如果包含，則作業還會添加[某些屬性](#rules-attributes) . **注意：** `rules`不能[`only/except`](#onlyexcept-basic)與[`only/except`](#onlyexcept-basic)不能結合使用，因為它是該功能的替代品. 如果嘗試執行此操作，則 linter 返回的`key may not be used with rules`錯誤`key may not be used with rules` . #### Rules attributes[](#rules-attributes "Permalink") `rules`允許的作業屬性是： * [`when`](#when) ：如果未定義，則默認為`when: on_success` . * 如果用作`when: delayed` ，則還需要`start_in` . * [`allow_failure`](#allow_failure) ：如果未定義，則默認為`allow_failure: false` . 如果一個規則的計算結果為 true，并且`when`具有除`never`以外的任何值`when` ，該作業將包括在管道中. 例如： ``` docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - if: '$CI_COMMIT_BRANCH == "master"' when: delayed start_in: '3 hours' allow_failure: true ``` 將來可能會將其他作業配置添加到規則中. 如果沒有有用的東西，請[打開一個問題](https://gitlab.com/gitlab-org/gitlab/-/issues) . #### Rules clauses[](#rules-clauses "Permalink") 可用的規則子句為： | Clause | Description | | --- | --- | | [`if`](#rulesif) | 通過評估`if`語句在管道中添加或排除作業. 與[`only:variables`](#onlyvariablesexceptvariables)類似. | | [`changes`](#ruleschanges) | 根據更改的文件在管道中添加或排除作業. 與[`only:changes`](#onlychangesexceptchanges)相同. | | [`exists`](#rulesexists) | 根據特定文件的存在在管道中添加或排除作業. | Rules are evaluated in order until a match is found. If a match is found, the attributes are checked to see if the job should be added to the pipeline. If no attributes are defined, the defaults are: * `when: on_success` * `allow_failure: false` 作業已添加到管道中： * 如果規則匹配并且具有以下條件`when: on_success` ， `when: delayed` `when: on_success`或`when: always` . * 如果沒有規則匹配，但最后一個子句為`when: on_success` ， `when: delayed` `when: on_success`或`when: always` （無規則）. 作業未添加到管道： * 如果沒有規則匹配，并且在以下情況下沒有獨立的條件`when: on_success` ， `when: delayed` `when: on_success`或`when: always` . * 如果規則匹配，并且具有以下條件`when: never`作為屬性. 例如，使用`if`子句嚴格限制作業運行的時間： ``` job: script: "echo Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: manual allow_failure: true - if: '$CI_PIPELINE_SOURCE == "schedule"' ``` 在此示例中： * 如果管道用于合并請求，則第一個規則匹配，并且作業將添加到[合并請求管道](../merge_request_pipelines/index.html) ，其屬性為： * `when: manual` （手動工作） * `allow_failure: true` （即使未運行手動作業，也允許管道繼續運行） * 如果管道**不是**用于合并請求的，則第一條規則不匹配，并且第二條規則被評估. * 如果管道是計劃的管道，則第二條規則匹配，并將作業添加到計劃的管道. 由于未定義任何屬性，因此添加了： * `when: on_success` （默認） * `allow_failure: false` （默認） * 在**所有其他情況下** ，沒有規則匹配，因此該作業**不會**添加到任何其他管道. 另外，您可以定義一組規則以在某些情況下排除作業，但在所有其他情況下運行它們： ``` job: script: "echo Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' when: never - if: '$CI_PIPELINE_SOURCE == "schedule"' when: never - when: on_success ``` * 如果管道用于合并請求， **則不**會將作業添加到管道. * 如果管道是計劃的管道， **則不**會將作業添加到管道. * 在**所有其他情況下** ，將使用以下時間將作業添加到管道中`when: on_success` . **注意**如果你使用`when: on_success` ， `always` ，或`delayed`作為最終的規則，兩個同時進行的管道可能會啟動. 推送管道和合并請求管道都可以由同一事件觸發（對于打開的合并請求，將其推送到源分支）. 請參閱[`rules`之間](#differences-between-rules-and-onlyexcept)的[重要區別， `only` / `except`](#differences-between-rules-and-onlyexcept)以獲取更多詳細信息. #### Differences between `rules` and `only`/`except`[](#differences-between-rules-and-onlyexcept "Permalink") 默認情況下， `only/except`定義的作業不會觸發合并請求管道. 您必須`only: merge_requests`明確添加`only: merge_requests` . 用`rules`定義的作業可以觸發所有類型的管道. 您不必顯式配置每種類型. 例如： ``` job: script: "echo This creates double pipelines!" rules: - if: '$CUSTOM_VARIABLE == "false"' when: never - when: always ``` This job does not run when `$CUSTOM_VARIABLE` is false, but it *does* run in **all** other pipelines, including **both** push (branch) and merge request pipelines. With this configuration, every push to an open merge request’s source branch causes duplicated pipelines. Explicitly allowing both push and merge request pipelines in the same job could have the same effect. 我們建議使用[`workflow: rules`](#workflowrules)來限制允許的管道類型. 僅允許合并請求管道，或僅允許分支管道，可以消除重復的管道. 另外，您也可以使用最終避免重寫規則更嚴格，或`when` （ `always` ， `on_success`或`delayed` ）. 另外，我們不建議在同一管道中將`only/except`作業與`rules`作業混合使用. 它可能不會導致 YAML 錯誤，但是由于`only/except`和`rules`默認行為不同，因此調試確切的執行行為可能會很復雜. ##### `rules:if`[](#rulesif "Permalink") `rules:if`子句通過評估簡單的`if`語句來確定是否將作業添加到管道. 如果`if`語句為 true，則將作業包括在管道中或從管道中排除. 用簡單的英語， `if`規則可以解釋為之一： * "如果此規則評估為 true，則添加作業"（默認值）. * "如果該規則評估為 true，則不要添加作業"（通過添加`when: never` ）. `rules:if`與`only:variables`略有不同，每個規則僅接受一個表達式字符串，而不是它們的數組. 可以使用`&&`或`||`將要求值的任何表達式集組合為一個表達式. ，并使用[變量匹配語法](../variables/README.html#syntax-of-environment-variable-expressions) . `if:` clauses are evaluated based on the values of [predefined environment variables](../variables/predefined_variables.html) or [custom environment variables](../variables/README.html#custom-environment-variables). 例如： ``` job: script: "echo Hello, Rules!" rules: - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: always - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' when: manual allow_failure: true - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible ``` 有關確定`when`上班的邏輯的一些詳細信息： * 如果提供的規則都不匹配，則將作業設置為以下`when: never` ，并且不包含在管道中. * 不帶任何條件子句的規則，例如不帶`if`或`changes`的`when`或`allow_failure`規則，始終匹配，并且在達到條件時始終使用. * If a rule matches and has no `when` defined, the rule uses the `when` defined for the job, which defaults to `on_success` if not defined. * 您可以定義`when`一次按規則，或在一次作業級別，它適用于所有規則. 你不能混用`when`在作業水平`when`的規則. 對于類似于[`only` / `except`關鍵字的](#onlyexcept-basic)行為，可以檢查`$CI_PIPELINE_SOURCE`變量的值. | Value | Description | | --- | --- | | `push` | 對于由`git push`事件觸發的管道，包括分支和標簽. | | `web` | 對于使用 GitLab UI 中的**"運行管道"**按鈕創建的**管道** ，請從項目的**CI / CD>"管道"**部分. | | `trigger` | For pipelines created by using a trigger token. | | `schedule` | For [scheduled pipelines](../pipelines/schedules.html). | | `api` | 對于由[管道 API](../../api/pipelines.html#create-a-new-pipeline)觸發的[管道](../../api/pipelines.html#create-a-new-pipeline) . | | `external` | 使用除 GitLab 以外的 CI 服務時. | | `pipelines` | 對于通過[將 API 與`CI_JOB_TOKEN`一起使用](../triggers/README.html#when-used-with-multi-project-pipelines)創建的多項目管道. | | `chat` | 對于使用[GitLab ChatOps](../chatops/README.html)命令創建的管道. | | `webide` | 對于使用[WebIDE](../../user/project/web_ide/index.html)創建的管道. | | `merge_request_event` | 對于在創建或更新合并請求時創建的管道. 啟用[合并請求管道](../merge_request_pipelines/index.html) ， [合并結果管道](../merge_request_pipelines/pipelines_for_merged_results/index.html)和[合并序列所](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.html)必需. | | `external_pull_request_event` | 在 GitHub 上創建或更新外部拉取請求時. 有關[外部拉取請求，](../ci_cd_for_external_repos/index.html#pipelines-for-external-pull-requests)請參見[管道](../ci_cd_for_external_repos/index.html#pipelines-for-external-pull-requests) . | | `parent_pipeline` | 對于由具有`rules`的[父/子](../parent_child_pipelines.html)管道觸發的[管道](../parent_child_pipelines.html) ，請在子管道配置中使用它，以便可以由父管道觸發. | 例如： ``` job: script: "echo Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "schedule"' when: manual allow_failure: true - if: '$CI_PIPELINE_SOURCE == "push"' ``` 此示例在以下情況下在計劃的管道或推送管道（到分支或標簽）中將其作為手動作業運行`when: on_success` （默認）. 不會將作業添加到任何其他管道類型. 另一個例子： ``` job: script: "echo Hello, Rules!" rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "schedule"' ``` 本示例將作業作為以下`when: on_success`運行`when: on_success`在[合并請求管道](../merge_request_pipelines/index.html)和計劃管道中的`when: on_success`作業. 它不能在任何其他管道類型中運行. `if`子句的其他常用變量： * `if: $CI_COMMIT_TAG` ：是否為標簽推送更改. * `if: $CI_COMMIT_BRANCH` ：是否將更改推送到任何分支. * `if: '$CI_COMMIT_BRANCH == "master"'` ：如果將更改推送到`master` . * `if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'` ：如果將更改推送到默認分支（通常是`master` ）. 如果在可能具有不同默認分支的多個項目中重用同一配置，則很有用. * `if: '$CI_COMMIT_BRANCH =~ /regex-expression/'` ：如果 commit 分支與正則表達式匹配. * `if: '$CUSTOM_VARIABLE !~ /regex-expression/'` ：如果[自定義變量](../variables/README.html#custom-environment-variables) `CUSTOM_VARIABLE`與正則表達式**不**匹配. * `if: '$CUSTOM_VARIABLE == "value1"'` ：如果自定義變量`CUSTOM_VARIABLE`恰好是`value1` . ##### `rules:changes`[](#ruleschanges "Permalink") 要確定是否應將作業添加到管道，請使用`rules: changes`子句檢查由 Git push 事件更改的文件. `rules: changes`工作方式與[`only: changes`和`except: changes`](#onlychangesexceptchanges) ，接受路徑數組. 同樣，如果沒有 Git 推送事件，則始終返回 true. 它僅應用于分支管道或合并請求管道. 例如： ``` workflow: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - changes: - Dockerfile when: manual allow_failure: true ``` 在此示例中： * [`workflow: rules`](#workflowrules)僅允許用于所有作業的合并請求的管道. * 如果`Dockerfile`已更改，則將作業作為手動作業添加到管道中，并允許管道繼續運行，即使未觸發該作業（ `allow_failure: true` ）. * 如果`Dockerfile`尚未更改，請不要將作業添加到任何管道（與`when: never`相同）. ##### `rules:exists`[](#rulesexists "Permalink") 在 GitLab 12.4 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) . `exists` accepts an array of paths and will match if any of these paths exist as files in the repository. 例如： ``` job: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - exists: - Dockerfile ``` 您還可以使用全局模式來匹配存儲庫中任何目錄中的多個文件. 例如： ``` job: script: bundle exec rspec rules: - exists: - spec/**.rb ``` **注意：**出于性能原因，使用`exists`與模式限制為 10000 個檢查. 第 10000 次檢查后，帶有圖案化球形的規則將始終匹配. ##### `rules:allow_failure`[](#rulesallow_failure "Permalink") 在 GitLab 12.8 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) . 您可以在`rules:`使用[`allow_failure: true`](#allow_failure) `rules:`在不停止管道本身的情況下允許作業失敗或手動作業等待操作. 所有使用`rules:`作業`rules:`默認為`allow_failure: false`如果`allow_failure:` ， `allow_failure: false` . 規則級`rules:allow_failure`選項將覆蓋作業級[`allow_failure`](#allow_failure)選項，并且僅在特定規則觸發作業時才應用. ``` job: script: "echo Hello, Rules!" rules: - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' when: manual allow_failure: true ``` 在此示例中，如果第一個規則匹配，則作業將具有以下`when: manual`和`allow_failure: true` . #### Complex rule clauses[](#complex-rule-clauses "Permalink") 要使`if` ， `changes`和`exists`子句與 AND 結合在一起，請在同一規則中使用它們. 在以下示例中： * 如果`Dockerfile`或`Dockerfile` `docker/scripts/`任何文件已更改并且`$VAR == "string value"`我們將手動運行作業. * 否則，該作業將不會包含在管道中. ``` docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - if: '$VAR == "string value"' changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. - Dockerfile - docker/scripts/* when: manual # - when: never would be redundant here, this is implied any time rules are listed. ``` 當前`only`可用于/ `except`關鍵字（例如`branches`或`refs`在`rules`尚不可用，因為在這種情況下，它們的用法和行為被單獨考慮. 我們將在[史詩](https://gitlab.com/groups/gitlab-org/-/epics/2783)中討論未來的關鍵字改進， [以改進`rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783) ，任何人都可以添加建議或請求. ### `only`/`except` (basic)[](#onlyexcept-basic "Permalink") **注意：** [`rules`](#rules)語法是一種改進的功能更強大的解決方案，用于定義作業何時運行或不運行. 考慮使用`rules`而不是`only/except`來最大程度地利用管道. `only`和`except`是用于設置作業策略以限制創建作業時間的兩個參數： 1. `only` defines the names of branches and tags for which the job will run. 2. `except`定義將**不**運行作業的分支和標簽的名稱. 有一些適用于作業策略的規則： * `only`且`except` . 如果作業規范中同時定義了`only`和`except` ，則 ref 將被`only`和`except`過濾. * `only`且`except`允許使用正則表達式（ [受支持的 regexp 語法](#supported-onlyexcept-regexp-syntax) ）. * `only`且`except`允許指定存儲庫路徑以過濾派生作業. 此外， `only`和`except`允許使用特殊關鍵字： | **Value** | **Description** | | --- | --- | | `branches` | 當管道的 Git 參考是分支時. | | `tags` | 當管道的 Git 參考是標簽時. | | `api` | 對于由[管道 API](../../api/pipelines.html#create-a-new-pipeline)觸發的[管道](../../api/pipelines.html#create-a-new-pipeline) . | | `external` | 使用除 GitLab 以外的 CI 服務時. | | `pipelines` | 對于通過將 API 與`CI_JOB_TOKEN`一起使用創建的多項目管道. | | `pushes` | 對于由`git push`事件觸發的管道，包括分支和標簽. | | `schedules` | For [scheduled pipelines](../pipelines/schedules.html). | | `triggers` | 對于使用觸發令牌創建的管道. | | `web` | 對于使用 GitLab UI 中的**"運行管道"**按鈕創建的**管道** ，請從項目的**CI / CD>"管道"**部分. | | `merge_requests` | 對于在創建或更新合并請求時創建的管道. 啟用[合并請求管道](../merge_request_pipelines/index.html) ， [合并結果管道](../merge_request_pipelines/pipelines_for_merged_results/index.html)和[合并序列](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.html) . | | `external_pull_requests` | 在 GitHub 上創建或更新[外部拉取請求時](../ci_cd_for_external_repos/index.html#pipelines-for-external-pull-requests) （有關[外部拉取請求，](../ci_cd_for_external_repos/index.html#pipelines-for-external-pull-requests)請參見[管道](../ci_cd_for_external_repos/index.html#pipelines-for-external-pull-requests) ）. | | `chat` | 對于使用[GitLab ChatOps](../chatops/README.html)命令創建的管道. | 在下面的例子中， `job`將只運行了與裁判開始`issue-` ，而所有分支機構將被忽略： ``` job: # use regexp only: - /^issue-.*$/ # use special keyword except: - branches ``` 模式匹配默認情況下區分大小寫. 使用`i`標志修飾符，例如`/pattern/i` ，使模式不區分大小寫： ``` job: # use regexp only: - /^issue-.*$/i # use special keyword except: - branches ``` 在此示例中， `job`僅對標記了標簽的引用運行，或者如果通過 API 觸發器或[管道時間表](../pipelines/schedules.html)明確請求構建，則`job`將運行： ``` job: # use special keywords only: - tags - triggers - schedules ``` 存儲庫路徑可用于僅對父存儲庫執行作業，而不能用于派生： ``` job: only: - branches@gitlab-org/gitlab except: - master@gitlab-org/gitlab - /^release/.*$/@gitlab-org/gitlab ``` 上面的示例將為`gitlab-org/gitlab`上的所有分支運行`job` ，但`master`和名稱以`release/` `gitlab-org/gitlab`分支除外. 如果作業沒有`only`規則，則默認情況下`only: ['branches', 'tags']` . 如果沒有`except`規則，則為空. 例如， ``` job: script: echo 'test' ``` 轉換為： ``` job: script: echo 'test' only: ['branches', 'tags'] ``` #### Regular expressions[](#regular-expressions "Permalink") 因為`@`用于表示 ref 的存儲庫路徑的開頭，所以匹配正則表達式中包含`@`字符的 ref 名稱需要使用十六進制字符代碼匹配`\x40` . 正則表達式只能匹配標簽或分支名稱. 如果給定存儲庫路徑，則始終在字面上匹配. 如果必須使用正則表達式來匹配標記或分支名稱，則模式的整個 ref 名稱部分必須是正則表達式，并且必須用`/`括起來. （在結束符`/`之后附加正則表達式標志.）因此`issue-/.*/`不能匹配所有以`issue-`開頭的標記名或分支名. **提示**使用定位符`^`和`$`避免正則表達式僅匹配標記名稱或分支名稱的子字符串. 例如， `/^issue-/` `/^issue-.*$/` `/^issue-/`等效于`/^issue-/` `/^issue-.*$/` `/^issue-/` ，而只是`/issue/`也會匹配一個名為`/^issue-.*$/` `severe-issues`的分支. #### Supported `only`/`except` regexp syntax[](#supported-onlyexcept-regexp-syntax "Permalink") **警告：**這是 GitLab 11.9.4 引入的重大更改. 在 GitLab 11.9.4 中，GitLab 開始內部將`only`用于參數（參數`except` regexp 轉換為[RE2](https://github.com/google/re2/wiki/Syntax) . 這意味著僅支持[Ruby Regexp](https://ruby-doc.org/core/Regexp.html)提供的功能子集. 由于計算復雜性， [RE2](https://github.com/google/re2/wiki/Syntax)限制了所提供的功能集，這意味著某些功能在 GitLab 11.9.4 中變得不可用. 例如，負面的前瞻. For GitLab versions from 11.9.7 and up to GitLab 12.0, GitLab provides a feature flag that can be enabled by administrators that allows users to use unsafe regexp syntax. This brings compatibility with previously allowed syntax version and allows users to gracefully migrate to the new syntax. ``` Feature.enable(:allow_unsafe_ruby_regexp) ``` ### `only`/`except` (advanced)[](#onlyexcept-advanced "Permalink") **警告：**這是*Alpha 版*功能，如有更改，恕不另行通知！ GitLab 支持簡單策略和復雜策略，因此可以使用數組和哈希配置方案. 有四個鍵可用： * `refs` * `variables` * `changes` * `kubernetes` 如果`only`或`except`下使用多個鍵，則這些鍵將被視為單個聯合表達式. 那是： * `only:`表示"如果所有條件都匹配，則包括此作業". * `except:`表示"如果任何條件匹配，則排除此工作". 使用`only` ，各個鍵在邏輯上由 AND 聯接： > （任何參考）AND（任何變量）AND（任何變化）AND（如果 Kubernetes 是活動的） 在下面的示例中， `only`在滿足以下**所有條件** `only`創建`test`作業： * 該管道已被[調度](../../user/project/pipelines/schedules.html) **或**正在`master`管道運行. * `variables`關鍵字匹配. * `kubernetes`服務在項目上處于活動狀態. ``` test: script: npm run test only: refs: - master - schedules variables: - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/ kubernetes: active ``` `except`被實現為對此完整表達式的否定： > NOT（（任何參考）AND（任何變量）AND（任何變化）AND（如果 Kubernetes 處于活動狀態）） This means the keys are treated as if joined by an OR. This relationship could be described as: > （任何參考）或（任何變量）或（任何變化）或（如果 Kubernetes 處于活動狀態） 在以下示例中，如果滿足以下**任一條件** ，則**不會**創建`test`作業： * 該管道的運行`master` . * 存儲庫的根目錄中的`README.md`文件進行了更改. ``` test: script: npm run test except: refs: - master changes: - "README.md" ``` #### `only:refs`/`except:refs`[](#onlyrefsexceptrefs "Permalink") GitLab 10.0 中引入的`refs`策略. `refs`策略可以采用與[簡化的 only / except 配置](#onlyexcept-basic)相同的值. 在下面的示例中，僅在`master`分支[計劃](../pipelines/schedules.html)或運行管道時才創建`deploy`作業： ``` deploy: only: refs: - master - schedules ``` #### `only:kubernetes`/`except:kubernetes`[](#onlykubernetesexceptkubernetes "Permalink") GitLab 10.0 中引入的`kubernetes`策略. The `kubernetes` strategy accepts only the `active` keyword. 在下面的示例中，僅當項目中的 Kubernetes 服務處于活動狀態時，才將創建`deploy`作業： ``` deploy: only: kubernetes: active ``` #### `only:variables`/`except:variables`[](#onlyvariablesexceptvariables "Permalink") GitLab 10.7 中引入了`variables`策略. `variables`關鍵字用于定義變量表達式. 換句話說，您可以使用預定義變量/項目/組或環境范圍的變量來定義 GitLab 將要評估的表達式，以決定是否應創建作業. 使用變量表達式的示例： ``` deploy: script: cap staging deploy only: refs: - branches variables: - $RELEASE == "staging" - $STAGING ``` 另一個用例是根據提交消息排除作業： ``` end-to-end: script: rake test:end-to-end except: variables: - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/ ``` 了解有關[變量表達式的](../variables/README.html#environment-variables-expressions)更多信息. #### `only:changes`/`except:changes`[](#onlychangesexceptchanges "Permalink") `changes` GitLab 11.4 中[引入的](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232)策略. 利用`changes`與關鍵字`only`或`except`能夠基于通過推送操作事件被修改的文件定義，如果一個工作應該被創建. 這意味著`only:changes`策略對以下情況的管道很有用： * `$CI_PIPELINE_SOURCE == 'push'` * `$CI_PIPELINE_SOURCE == 'merge_request_event'` * `$CI_PIPELINE_SOURCE == 'external_pull_request_event'` 如果沒有 Git 推送事件（例如，對于具有[上述三個之外的源的](../variables/predefined_variables.html)管道），則`changes`無法確定給定文件是新文件還是舊文件，并且始終返回 true. `only: changes`使用的一個基本示例`only: changes` ： ``` docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . only: changes: - Dockerfile - docker/scripts/* - dockerfiles/**/* - more_scripts/*.{rb,py,sh} ``` 在上述場景中，當將提交推送到 GitLab 中的現有分支時，它會創建并觸發`docker build`作業，只要其中一個提交包含對以下任何一項的更改： * The `Dockerfile` file. * `docker/scripts/`目錄中的任何文件. * `dockerfiles`目錄中的任何文件和子目錄. * `more_scripts`目錄中具有`rb` ， `py` ， `sh`擴展名的`more_scripts`文件. **警告：**如果`only:changes`使用`only:changes` [僅允許在管道成功的情況下合并合并請求，則](../../user/project/merge_requests/merge_when_pipeline_succeeds.html#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds)如果不[同時使用`only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests)則可能導致不良行為. 您還可以使用 glob 模式來匹配存儲庫的根目錄或存儲庫內*任何*目錄中的多個文件，但是它們必須用雙引號引起來，否則 GitLab 將無法解析`.gitlab-ci.yml` . 例如： ``` test: script: npm run test only: changes: - "*.json" - "**/*.sql" ``` 如果在存儲庫根目錄中任何擴展名為`.md`文件中檢測到更改，以下示例將跳過`build`作業： ``` build: script: npm run build except: changes: - "*.md" ``` **警告：**當[將此功能與*沒有*合并請求管道的新分支或標記一起使用](#using-onlychanges-without-pipelines-for-merge-requests)時，需要注意一些要點.**警告：**在[計劃的管道上使用此功能](#using-onlychanges-with-scheduled-pipelines)時，需要注意一些要點. ##### Using `only:changes` with pipelines for merge requests[](#using-onlychanges-with-pipelines-for-merge-requests "Permalink") 使用[用于合并請求的管道，](../merge_request_pipelines/index.html)可以根據在合并請求中修改的文件來定義要創建的作業. 為了推斷源分支的正確基礎 SHA，建議`only: [merge_requests]`將此關鍵字與`only: [merge_requests]` . 這樣，可以從任何進一步的提交中正確計算出文件差異，因此可以在管道中正確測試合并請求中的所有更改. 例如： ``` docker build service one: script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . only: refs: - merge_requests changes: - Dockerfile - service-one/**/* ``` 在上述情況下，如果創建或更新了合并請求，從而更改了`service-one`目錄中的文件或`Dockerfile` ，則 GitLab 將創建并觸發`Dockerfile` `docker build service one`作業. Note that if [pipelines for merge requests](../merge_request_pipelines/index.html) is combined with `only: [change]`, but `only: [merge_requests]` is omitted, there could be unwanted behavior. 例如： ``` docker build service one: script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . only: changes: - Dockerfile - service-one/**/* ``` 在上面的示例中，管道可能由于對`service-one/**/*`的文件的更改而失敗. 然后可以推送更高版本的提交，該提交不包括對該文件的任何更改，但包括對`Dockerfile`更改，并且該管道可以通過，因為它僅測試對`Dockerfile`的更改. GitLab 會檢查**最近** **通過的** **管道** ，并且將合并請求顯示為可合并，盡管較早的管道失敗是由于尚未更正的更改引起的. 使用此配置時，必須注意檢查最新的管道是否正確地糾正了先前管道的任何故障. ##### Using `only:changes` without pipelines for merge requests[](#using-onlychanges-without-pipelines-for-merge-requests "Permalink") 如果沒有[用于合并請求的](../merge_request_pipelines/index.html)管道，則管道將在與合并請求沒有明確關聯的分支或標簽上運行. 在這種情況下，將使用先前的 SHA 來計算 diff，這等效于`git diff HEAD~` . 這可能會導致某些意外行為，包括： * When pushing a new branch or a new tag to GitLab, the policy always evaluates to true. * 推送新提交時，更改的文件將使用先前的提交作為基礎 SHA 進行計算. ##### Using `only:changes` with scheduled pipelines[](#using-onlychanges-with-scheduled-pipelines "Permalink") `only:changes`在[Scheduled 管道中](../pipelines/schedules.html)始終評估為" true". 當計劃的管道運行時，所有文件都被視為"已更改". ### `needs`[](#needs "Permalink") 版本歷史 * 在 GitLab 12.2 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) . * 在 GitLab 12.3 中， `needs`陣列中的最大作業數從 5 個增加到 50 個. * 在 GitLab 12.8 中[引入的](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) `needs: []`使作業立即開始. `needs:`關鍵字可無序執行作業，使您可以在`.gitlab-ci.yml`實現有[向無環圖](../directed_acyclic_graph/index.html) . 這樣，您無需等待階段順序即可運行某些作業，而無需等待其他任務，因此您可以讓多個階段同時運行. 讓我們考慮以下示例： ``` linux:build: stage: build mac:build: stage: build lint: stage: test needs: [] linux:rspec: stage: test needs: ["linux:build"] linux:rubocop: stage: test needs: ["linux:build"] mac:rspec: stage: test needs: ["mac:build"] mac:rubocop: stage: test needs: ["mac:build"] production: stage: deploy ``` 本示例創建四個執行路徑： * 棉短絨：在`lint`作業將立即運行，而無需等待`build`階段完成，因為它沒有需求（ `needs: []` * Linux 路徑： `linux:build`作業完成后，將立即運行`linux:rspec`和`linux:rubocop`作業，而無需等待`mac:build`完成. * macOS 路徑： `mac:build`作業完成后，將立即運行`mac:rspec`和`mac:rubocop`作業，而無需等待`linux:build`完成. * `production`作業將在所有先前的作業完成后立即執行； 在這種情況下： `linux:build` ， `linux:rspec` ， `linux:rubocop` ， `mac:build` ， `mac:rspec` ， `mac:rubocop` . #### Requirements and limitations[](#requirements-and-limitations "Permalink") * 如果`needs:`設置為指向`only/except`因`only/except`規則而未實例化的作業，或者不存在，則創建管道時會出現 YAML 錯誤. * `needs:`數組中單個作業可能需要的最大作業數是有限的： * 對于 GitLab.com，限制為十個. 有關更多信息，請參見[基礎結構問題](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541) . * 對于自我管理的實例，限制為： * 10，如果`ci_dag_limit_needs`功能標志已啟用（默認）. * 50，如果`ci_dag_limit_needs`功能標記被禁用. * 如果`needs:`是指標記為" `parallel:`的作業. 當前作業將取決于創建的所有并行作業. * `needs:`類似于`dependencies:`它需要使用之前階段的作業，這意味著不可能創建循環依賴關系. 在當前階段也不可能依賴于工作，但是[已計劃了](https://gitlab.com/gitlab-org/gitlab/-/issues/30632)支持. * 與上述相關，必須為所有具有關鍵字`needs:`或由一個人引用的作業明確定義階段. ##### Changing the `needs:` job limit[](#changing-the-needs-job-limit "Permalink") 可以在`needs:`定義的最大作業數`needs:`默認為 10，但可以通過功能標志更改為 50\. 要將限制更改為 50，請[啟動 Rails 控制臺會話](../../administration/troubleshooting/debug.html#starting-a-rails-console-session)并運行： ``` Feature::disable(:ci_dag_limit_needs) ``` 要將其設置回 10，請運行相反的命令： ``` Feature::enable(:ci_dag_limit_needs) ``` #### Artifact downloads with `needs`[](#artifact-downloads-with-needs "Permalink") [介紹](https://gitlab.com/gitlab-org/gitlab/-/issues/14311)在 GitLab v12.6. 在使用`needs` ，可通過`artifacts: true` （默認）或`artifacts: false`來控制工件下載. 從 GitLab 12.6 開始，您不能將[`dependencies`](#dependencies)關鍵字與控制作業中工件下載的`needs`結合使用. `dependencies`在不使用`needs`作業中仍然有效. 在以下示例中， `rspec`作業將下載`build_job`工件，而`rubocop`作業則不會： ``` build_job: stage: build artifacts: paths: - binaries/ rspec: stage: test needs: - job: build_job artifacts: true rubocop: stage: test needs: - job: build_job artifacts: false ``` 另外，在下面的三個語法示例中， `rspec`作業將從所有三個`build_jobs`下載工件，因為`artifacts`對于`build_job_1`是 true，并且對于`build_job_2`和`build_job_3`都**默認**為 true. ``` rspec: needs: - job: build_job_1 artifacts: true - job: build_job_2 - build_job_3 ``` #### Cross project artifact downloads with `needs`[](#cross-project-artifact-downloads-with-needs-premium "Permalink") [介紹](https://gitlab.com/gitlab-org/gitlab/-/issues/14311)在 GitLab v12.7. `needs`可用于從[同一項目中其他 ref](#artifact-downloads-between-pipelines-in-the-same-project)或不同項目中的管道上的多達五個作業的工件中下載工件： ``` build_job: stage: build script: - ls -lhR needs: - project: group/project-name job: build-1 ref: master artifacts: true ``` `build_job`將從`group/project-name`項目的`master`分支上的最新成功`build-1`作業中下載工件. ##### Artifact downloads between pipelines in the same project[](#artifact-downloads-between-pipelines-in-the-same-project "Permalink") 通過將`project`關鍵字設置為當前項目的名稱，并指定引用，可以使用`needs`從當前項目的不同管道中下載工件. 在下面的示例中， `build_job`將使用`other-ref` ref 下載最新成功的`build-1`作業的工件： ``` build_job: stage: build script: - ls -lhR needs: - project: group/same-project-name job: build-1 ref: other-ref artifacts: true ``` **注意：**不支持從[`parallel:`](#parallel)運行的作業中下載工件[`parallel:`](#parallel) ### `tags`[](#tags "Permalink") `tags`用于從允許運行該項目的所有 Runner 列表中選擇特定的 Runner. 在 Runner 的注冊過程中，您可以指定 Runner 的標簽，例如`ruby` ， `postgres` ， `development` . `tags`可讓您為具有指定標簽的跑步者運行作業： ``` job: tags: - ruby - postgres ``` 上面的規范將確保`job`由同時定義了`ruby`和`postgres`標簽的 Runner 構建. 標簽也是在不同平臺上運行不同作業的好方法，例如，給定帶有`osx`標簽的 OS X Runner 和帶有`windows`標簽的 Windows Runner，以下作業將在各自的平臺上運行： ``` windows job: stage: - build tags: - windows script: - echo Hello, %USERNAME%! osx job: stage: - build tags: - osx script: - echo "Hello, $USER!" ``` ### `allow_failure`[](#allow_failure "Permalink") `allow_failure`允許作業失敗，而不會影響其余 CI 套件. 默認值是`false` ，除了使用`when: manual`語法的[手動](#whenmanual)作業之外，除非使用[`rules:`](#rules)語法，否則所有作業默認為 false， *包括* `when: manual`作業. 啟用后，如果作業失敗，該作業將在用戶界面中顯示橙色警告. 但是，管道的邏輯流程將認為作業成功/通過，并且不會被阻塞. 假設所有其他作業均成功，則該作業的階段及其管道將顯示相同的橙色警告. 但是，關聯的提交將被標記為"通過"，而不會發出警告. 在下面的示例中， `job1`和`job2`將并行運行，但是如果`job1`失敗，它不會停止下一階段的運行，因為它標記有`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 "Permalink") `when`用于實現在發生故障或發生故障時運行的作業. `when`可以被設置為以下值中的一個： 1. `on_success`僅在先前階段中的所有作業都成功（或因為標記為`allow_failure`而被視為成功）時才執行作業. 這是默認值. 2. `on_failure`僅在`on_failure`中的至少一項作業失敗時才執行作業. 3. `always` -執行作業，而不管先前階段的作業狀態如何. 4. `manual` -手動執行作業（在 GitLab 8.10 中已添加）. 在下面閱讀有關[手動操作的信息](#whenmanual) . 5. `delayed` -一定時間后執行作業（在 GitLab 11.14 中已添加）. 在下面閱讀有關[延遲動作的信息](#whendelayed) . For example: ``` 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. 無論成功與失敗，始終執行`cleanup_job`作為管道的最后一步. 3. 允許您從 GitLab 的 UI 手動執行`deploy_job` . #### `when:manual`[](#whenmanual "Permalink") 版本歷史 * 在 GitLab 8.10 中引入. * 在 GitLab 9.0 中引入了阻止手動操作. * GitLab 9.2 中引入了受保護的操作. 手動操作是一種特殊類型的作業，不會自動執行，需要用戶明確啟動. 手動操作的示例用法是部署到生產環境. 可以從管道，作業，環境和部署視圖開始手動操作. 在[環境文檔中](../environments/index.html#configuring-manual-deployments)閱讀更多[內容](../environments/index.html#configuring-manual-deployments) . 手動操作可以是可選的或阻止的. 阻止手動操作將在定義此操作的階段阻止管道的執行.當有人通過單擊*播放*按鈕執行阻止手動操作時，可以恢復管道的執行. 當管道被阻塞時，如果設置了"管道成功時合并"，則不會被合并. 阻塞的管道也確實有一種特殊的狀態，稱為*手動* . 使用`when:manual`語法`when:manual` ，默認情況下手動操作是非阻塞的. 如果要進行手動操作阻止，則必須在`.gitlab-ci.yml`的作業定義中添加`allow_failure: false` . 可選的手動操作具有`allow_failure: true`默認情況下設置為`allow_failure: true` ，并且它們的狀態不影響總體管道狀態. 因此，如果手動操作失敗，則管道最終將成功. **注意：**使用[`rules:`](#rules) ， `allow_failure`默認為`false` ，包括手動作業. 手動操作被視為寫操作，因此當用戶想要觸發操作時，將使用[受保護分支的](../../user/project/protected_branches.html)權限. 換句話說，為了觸發分配給正在為其運行管道的分支的手動操作，用戶需要具有合并到該分支的能力. 可以使用受保護的環境來更嚴格地[保護手動部署](#protecting-manual-jobs-premium) ，以防止未經授權的用戶運行. **注意：同時**使用`when:manual`和`trigger`導致錯誤`jobs:#{job-name} when should be on_success, on_failure or always` ，因為`when:manual`阻止使用觸發器. ##### Protecting manual jobs[](#protecting-manual-jobs-premium "Permalink") 可以使用[受保護的環境](../environments/protected_environments.html)來定義授權運行手動作業的用戶的精確列表. 通過僅允許與受保護環境關聯的用戶觸發手動作業，可以實現一些特殊用例，例如： * 更精確地限制可以部署到環境的人員. * 使管道能夠被阻塞，直到獲得批準的用戶"批準"為止. 為此，您必須： 1. 為作業添加`environment` . 例如： ``` deploy_prod: stage: deploy script: - echo "Deploy to production server" environment: name: production url: https://example.com when: manual only: - master ``` 2. 在" [受保護的環境"設置中](../environments/protected_environments.html#protecting-environments) ，選擇環境（上面的示例中為`production` ），然后將被授權觸發手動作業的用戶，角色或組添加到" **允許部署"**列表中. 只有該列表中的人員以及始終能夠使用受保護環境的 GitLab 管理員才能觸發此手動作業. 此外，如果通過添加`allow_failure: false`將手動作業定義為阻塞，則直到觸發手動作業后，管道的下`allow_failure: false`才會運行. 這可以用作一種方法，使定義的用戶列表可以通過觸發阻止的手動作業來"批準"后續的管道階段. #### `when:delayed`[](#whendelayed "Permalink") 在 GitLab 11.4 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) . 延遲的作業用于在一定時間后執行腳本. 如果要避免作業立即進入`pending`狀態，此功能很有用. 您可以使用`start_in`鍵設置時間段. 除非提供了單位，否則`start_in`鍵的值是以秒為單位的經過時間. `start_in`鍵必須小于或等于一周. 有效值的示例包括： * `'5'` * `10 seconds` * `30 minutes` * `1 day` * `1 week` 當階段中有延遲的工作時，直到延遲的工作完成，管道才能繼續進行. 這意味著該關鍵字也可以用于在不同階段之間插入延遲. 上一階段完成后，延遲作業的計時器立即啟動. 與其他類型的作業類似，延遲的作業計時器不會啟動，除非前一個階段通過. 以下示例創建一個名為`timed rollout 10%`的作業，該作業在上一階段完成后 30 分鐘執行： ``` timed rollout 10%: stage: deploy script: echo 'Rolling out 10% ...' when: delayed start_in: 30 minutes ``` 您可以通過單擊"停止"來停止延遲作業的活動計時器. （ **計劃外** ）按鈕. 除非您手動執行該作業，否則以后將永遠不會執行該作業. 您可以通過單擊" **播放"**按鈕立即開始延遲的作業. GitLab Runner 將很快開始您的工作并開始工作. ### `environment`[](#environment "Permalink") 版本歷史 * 在 GitLab 8.9 中引入. * 您可以閱讀有關環境的更多信息，并在[有關環境](../environments/index.html)的[文檔中](../environments/index.html)找到更多示例. `environment`用于定義作業部署到特定環境. 如果指定了`environment` ，但不存在該名稱下的環境，則將自動創建一個新環境. 以最簡單的形式，可以將`environment`關鍵字定義為： ``` deploy to production: stage: deploy script: git push production HEAD:master environment: production ``` 在上面的示例中，將`deploy to production`作業標記為正在部署到`production`環境. #### `environment:name`[](#environmentname "Permalink") 版本歷史 * 在 GitLab 8.11 中引入. * 在 GitLab 8.11 之前，環境的名稱可以定義為類似于`environment: production`的字符串`environment: production` . 現在推薦的方法是在`name`關鍵字下定義它. * `name`參數可以使用任何已定義的 CI 變量，包括預定義的安全變量和`.gitlab-ci.yml` [`variables`](#variables) . 但是，您不能使用`script`下定義的變量. `environment`名稱可以包含： * letters * digits * spaces * `-` * `_` * `/` * `$` * `{` * `}` 通用名稱是`qa` ， `staging`和`production` ，但是您可以使用與您的工作流程兼容的任何名稱. 除了在`environment`關鍵字之后直接定義環境名稱之外，還可以將其定義為單獨的值. 為此，請在`environment`下使用`name`關鍵字： ``` deploy to production: stage: deploy script: git push production HEAD:master environment: name: production ``` #### `environment:url`[](#environmenturl "Permalink") 版本歷史 * 在 GitLab 8.11 中引入. * 在 GitLab 8.11 之前，只能在 GitLab 的 UI 中添加 URL. 現在推薦的方法是在`.gitlab-ci.yml`定義它. * `url`參數可以使用任何已定義的 CI 變量，包括預定義的安全變量和`.gitlab-ci.yml` [`variables`](#variables) . 但是，您不能使用`script`下定義的變量. 這是一個可選值，設置該值時，它將在 GitLab 中的不同位置顯示按鈕，單擊這些按鈕會將您帶到定義的 URL. 在下面的示例中，如果作業成功完成，它將在合并請求和環境/部署頁面中創建按鈕，這些頁面將指向`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`[](#environmenton_stop "Permalink") 版本歷史 * 在 GitLab 8.13 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) . * 從 GitLab 8.14 開始，當您具有定義了停止動作的環境時，當刪除關聯的分支時，GitLab 將自動觸發停止動作. 可以通過在`on_stop`下定義的`on_stop`關鍵字來實現關閉（停止） `environment` . 它聲明運行另一個作業以關閉環境. 請閱讀`environment:action`部分以獲取示例. #### `environment:action`[](#environmentaction "Permalink") 在 GitLab 8.13 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) . `action`關鍵字將與`on_stop`結合使用，并在調用關閉環境的作業中定義. 舉個例子： ``` review_app: stage: deploy script: make deploy-app environment: name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review_app stop_review_app: stage: deploy variables: GIT_STRATEGY: none script: make delete-app when: manual environment: name: review/$CI_COMMIT_REF_NAME action: stop ``` 在上面的例子中，我們建立了`review_app`工作部署到`review`環境，我們還定義了一個新`stop_review_app`下工作`on_stop` . 一旦`review_app`作業成功完成，就會觸發`stop_review_app`根據什么下定義的作業`when` . 在這種情況下，我們將其設置為`manual`因此需要通過 GitLab 的 Web 界面進行[手動操作](#whenmanual)才能運行. 同樣在該示例中， `GIT_STRATEGY`設置為`none`以便當[自動觸發](../environments/index.html#automatically-stopping-an-environment) `stop_review_app`作業時，刪除分支后，GitLab Runner 將不會嘗試檢出代碼. **注意：**上面的示例覆蓋了全局變量. 如果停止環境作業依賴于全局變量，則可以在設置`GIT_STRATEGY`時使用[錨變量](#yaml-anchors-for-variables)來更改它，而不覆蓋全局變量. **需要** `stop_review_app`作業定義以下關鍵字： * `when` - [reference](#when) * `environment:name` * `environment:action` 此外，兩個作業都應具有匹配的[`rules`](../yaml/README.html#onlyexcept-basic)或[`only/except`](../yaml/README.html#onlyexcept-basic)配置[`only/except`](../yaml/README.html#onlyexcept-basic) . 在上面的示例中，如果配置不同，則`stop_review_app`作業可能未包含在所有包含`review_app`作業的管道中，并且將無法觸發該`action: stop`以自動停止環境. #### `environment:auto_stop_in`[](#environmentauto_stop_in "Permalink") 在 GitLab 12.8 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) . `auto_stop_in`關鍵字用于指定環境的生命周期，當 GitLab 過期時，它將自動停止它們. 例如， ``` review_app: script: deploy-review-app environment: name: review/$CI_COMMIT_REF_NAME auto_stop_in: 1 day ``` 當執行`review_app`作業并創建評論應用程序時，環境的生命周期設置為`1 day` . 有關更多信息，請參見[環境自動停止文檔.](../environments/index.html#environments-auto-stop) #### `environment:kubernetes`[](#environmentkubernetes "Permalink") 在 GitLab 12.6 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) . `kubernetes`塊用于將部署配置為與您的項目關聯的[Kubernetes 集群](../../user/project/clusters/index.html) . 例如： ``` deploy: stage: deploy script: make deploy-app environment: name: production kubernetes: namespace: production ``` 這將使用`production` [Kubernetes 名稱空間](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)設置`deploy`作業以部署到`production`環境. 有關更多信息，請參閱[`kubernetes`可用設置](../environments/index.html#configuring-kubernetes-deployments) . **注意：** [由 GitLab 管理的](../../user/project/clusters/index.html#gitlab-managed-clusters) Kubernetes 集群不支持 Kubernetes 配置. 要跟蹤對 GitLab 管理的集群的支持進度，請參閱[相關問題](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) . #### Dynamic environments[](#dynamic-environments "Permalink") 版本歷史 * 在 GitLab 8.12 和 GitLab Runner 1.6 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21971) . * `$CI_ENVIRONMENT_SLUG`是在 GitLab 8.15 中[引入的](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22864) . * `name`和`url`參數可以使用任何已定義的 CI 變量，包括預定義的安全變量和`.gitlab-ci.yml` [`variables`](#variables) . 但是，您不能使用`script`下定義的變量. 例如： ``` deploy as review app: stage: deploy script: make deploy environment: name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` `deploy as review app`作業將被標記為部署，以動態創建`review/$CI_COMMIT_REF_NAME`環境，其中`$CI_COMMIT_REF_NAME`是 Runner 設置的[環境變量](../variables/README.html) . `$CI_ENVIRONMENT_SLUG`變量基于環境名稱，但適合包含在 URL 中. 在這種情況下，如果" `deploy as review app`作業在名為`pow`的分支中運行，則可以使用`https://review-pow.example.com/`類的 URL 訪問此環境. 當然，這意味著托管應用程序的基礎服務器已正確配置. 常見的用例是為分支創建動態環境并將其用作 Review Apps. 您可以在[https://gitlab.com/gitlab-examples/review-apps-nginx/上](https://gitlab.com/gitlab-examples/review-apps-nginx/)查看使用 Review Apps 的簡單示例. ### `cache`[](#cache "Permalink") 版本歷史 * 在 GitLab Runner v0.7.0 中引入. * `cache`可以全局設置，也可以按作業設置. * 從 GitLab 9.0 起，默認情況下啟用緩存并在管道和作業之間共享緩存. * 從 GitLab 9.2 起，緩存將在[工件](#artifacts)之前恢復. **了解更多信息：**閱讀緩存工作原理，并在[緩存依賴文檔中](../caching/index.html)找到一些好的做法. `cache`用于指定應在作業之間緩存的文件和目錄的列表. 您只能使用本地工作副本中的路徑. 如果在作業范圍之外定義了`cache` ，則意味著已全局設置`cache` ，并且所有作業都將使用該定義. #### `cache:paths`[](#cachepaths "Permalink") 使用`paths`指令選擇要緩存的文件或目錄. 路徑是相對于項目目錄（ `$CI_PROJECT_DIR` ）的，不能直接鏈接到其外部. 可以使用遵循[通配符](https://en.wikipedia.org/wiki/Glob_(programming))模式的[通配符，](https://en.wikipedia.org/wiki/Glob_(programming))并且： * 在[GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620)和更高版本中，請選擇[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match) . * 在 GitLab Runner 12.10 及更早版本中， [`filepath.Match`](https://pkg.go.dev/path/filepath/#Match) . 將所有文件緩存在以`.apk`和`.config`文件結尾的`binaries`文件中： ``` rspec: script: test cache: paths: - binaries/*.apk - .config ``` 本地定義的緩存將覆蓋全局定義的選項. 以下`rspec`作業將僅緩存`binaries/` ： ``` cache: paths: - my/files rspec: script: test cache: key: rspec paths: - binaries/ ``` 請注意，由于緩存是在作業之間共享的，因此如果您為不同的作業使用不同的路徑，則還應該設置不同的**cache：key，**否則緩存內容可能會被覆蓋. #### `cache:key`[](#cachekey "Permalink") 在 GitLab Runner v1.0.0 中引入. 由于緩存是在作業之間共享的，因此如果您為不同的作業使用不同的路徑，則還應該設置不同的`cache:key`否則緩存內容可能會被覆蓋. `key`指令允許您定義作業之間的緩存相似性，從而允許為所有作業使用單個緩存，按作業緩存，按分支緩存或適合您工作流程的任何其他方式. 這樣，您可以微調緩存，從而允許您在不同作業甚至不同分支之間緩存數據. `cache:key`變量可以使用任何[預定義的變量](../variables/README.html) ，并且默認鍵（如果未設置）只是文字`default` ，這意味著從 GitLab 9.0 開始，默認情況下所有內容都在管道和作業之間共享. **注意：** `cache:key`變量不能包含`/`字符或等效的 URI 編碼的`/` ； 也禁止僅由點（ `.` ， `.` ）組成的值. 例如，要啟用每分支緩存： ``` cache: key: "$CI_COMMIT_REF_SLUG" paths: - binaries/ ``` 如果使用**Windows Batch**運行 Shell 腳本，則需要將`$`替換`$` `%` ： ``` cache: key: "%CI_COMMIT_REF_SLUG%" paths: - binaries/ ``` ##### `cache:key:files`[](#cachekeyfiles "Permalink") [介紹](https://gitlab.com/gitlab-org/gitlab/-/issues/18986)在 GitLab v12.5. The `cache:key:files` keyword extends the `cache:key` functionality by making it easier to reuse some caches, and rebuild them less often, which will speed up subsequent pipeline runs. 當包含`cache:key:files` ，還必須列出將用于生成密鑰的項目文件，最多兩個文件. 緩存`key`將是根據更改給定文件的最新提交（最多兩個，如果列出了兩個文件）計算出的 SHA 校驗和. 如果在任何提交中都沒有更改文件，則后備密鑰將為`default` . ``` cache: key: files: - Gemfile.lock - package.json paths: - vendor/ruby - node_modules ``` 在此示例中，我們將為 Ruby 和 Node.js 依賴關系創建一個緩存，該緩存與`Gemfile.lock`和`package.json`文件的當前版本相關`Gemfile.lock` . 只要這些文件之一發生更改，就會計算新的緩存鍵并創建新的緩存. 任何將來的作業都使用相同的`Gemfile.lock`和`package.json`和`cache:key:files`將使用新的緩存，而不是重建依賴關系. ##### `cache:key:prefix`[](#cachekeyprefix "Permalink") [介紹](https://gitlab.com/gitlab-org/gitlab/-/issues/18986)在 GitLab v12.5. `prefix`參數通過允許密鑰由給定的`prefix`與為`cache:key:files`計算的 SHA 組合而成，從而為`key:files`添加了額外的功能. 例如，添加`test`的`prefix`將導致鍵看起來像： `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` . 如果在任何提交中都未更改兩個文件，則將前綴添加到`default` ，因此示例中的鍵將為`test-default` . 像`cache:key`一樣， `prefix`可以使用任何[預定義的變量](../variables/README.html) ，但是不允許以下操作： * `/`字符（或等效的 URI 編碼的`/` ） * 僅由組成的值`.` （或等效的 URI 編碼的`.` ） ``` cache: key: files: - Gemfile.lock prefix: ${CI_JOB_NAME} paths: - vendor/ruby rspec: script: - bundle exec rspec ``` 例如，添加`$CI_JOB_NAME` `prefix`將使密鑰看起來像： `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` ，并且作業緩存在不同分支之間共享. 如果分支更改`Gemfile.lock` ，則該分支將為`cache:key:files`具有新的 SHA 校驗和. 將生成一個新的緩存密鑰，并為該密鑰創建一個新的緩存. 如果未找到`Gemfile.lock` ，則將前綴添加到`default` ，因此示例中的鍵將為`rspec-default` . #### `cache:untracked`[](#cacheuntracked "Permalink") 設置`untracked: true`以緩存 Git 存儲庫中所有未跟蹤的文件： ``` rspec: script: test cache: untracked: true ``` 緩存所有 Git 未跟蹤的文件和`binaries` ： ``` rspec: script: test cache: untracked: true paths: - binaries/ ``` #### `cache:policy`[](#cachepolicy "Permalink") 在 GitLab 9.4 中引入. 緩存作業的默認行為是在執行開始時下載文件，然后在結束時重新上傳文件. 這樣可以將作業所做的任何更改保留下來，以備將來運行，這被稱為" `pull-push`緩存策略. 如果您知道該作業不會更改緩存的文件，則可以通過設置`policy: pull`來跳過上載步驟`policy: pull`插入作業規范. 通常，這會在較早的階段與普通的緩存作業結合在一起，以確保不時更新緩存： ``` stages: - setup - test prepare: stage: setup cache: key: gems paths: - vendor/bundle script: - bundle install --deployment rspec: stage: test cache: key: gems paths: - vendor/bundle policy: pull script: - bundle exec rspec ... ``` 這有助于加快作業執行速度并減少緩存服務器上的負載，尤其是當您有大量并行使用緩存的作業時. 此外，如果您有一項作業無條件地重新創建了高速緩存而不參考其先前的內容，則可以使用`policy: push`該作業以跳過下載步驟. ### `artifacts`[](#artifacts "Permalink") 版本歷史 * 在非 Windows 平臺的 GitLab Runner v0.7.0 中引入. * Windows 支持已在 GitLab Runner v.1.0.0 中添加. * 從 GitLab 9.2 起，緩存將在工件之前恢復. * 并非所有執行程序都[受支持](https://docs.gitlab.com/runner/executors/) . * 默認情況下，僅為成功的作業收集作業工件. `artifacts`用于指定在[成功，失敗或始終成功](#artifactswhen)時應附加到作業的文件和目錄的列表. 作業完成后，工件將被發送到 GitLab，并可在 GitLab UI 中下載. [Read more about artifacts](../pipelines/job_artifacts.html). #### `artifacts:paths`[](#artifactspaths "Permalink") 路徑是相對于項目目錄（ `$CI_PROJECT_DIR` ）的，不能直接鏈接到其外部. 可以使用遵循[通配符](https://en.wikipedia.org/wiki/Glob_(programming))模式和[`filepath.Match`](https://s0golang0org.icopy.site/pkg/path/filepath/)的[通配符](https://en.wikipedia.org/wiki/Glob_(programming)) . 要限制特定作業將從中獲取工件的作業，請參閱[dependencies](#dependencies) . 發送所有`binaries`和`.config`文件： ``` artifacts: paths: - binaries/ - .config ``` 要禁用工件傳遞，請使用空的[依賴項](#dependencies)定義作業： ``` job: stage: build script: make build dependencies: [] ``` 您可能只想為標記的發行版創建構件，以避免用臨時構建構件填充構建服務器存儲. 僅為標簽創建工件（ `default-job`不會創建工件）： ``` default-job: script: - mvn test -U except: - tags release-job: script: - mvn package -U artifacts: paths: - target/*.war only: - tags ``` 您也可以為目錄使用通配符. 例如，如果要獲取以`xyz`結尾的目錄中的所有文件： ``` job: artifacts: paths: - path/*xyz/* ``` #### `artifacts:exclude`[](#artifactsexclude "Permalink") 版本歷史 * 在 GitLab 13.1 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) * 需要 GitLab Runner 13.1 `exclude`可以防止將文件添加到工件存檔中. 類似于[`artifacts:paths`](#artifactspaths) ， `exclude`路徑相對于項目目錄. 可以使用遵循[通配符](https://en.wikipedia.org/wiki/Glob_(programming))模式和[`filepath.Match`](https://s0golang0org.icopy.site/pkg/path/filepath/)的[通配符](https://en.wikipedia.org/wiki/Glob_(programming)) . 例如，所有的文件存儲在`binaries/` ，而不是`*.o`位于的子目錄中的文件`binaries/` ： ``` artifacts: paths: - binaries/ exclude: - binaries/**/*.o ``` 與[`artifacts:untracked`](#artifactsuntracked)匹配的文件也可以使用`artifacts:exclude` . #### `artifacts:expose_as`[](#artifactsexpose_as "Permalink") 在 GitLab 12.5 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) . 關鍵字`expose_as`可用于在[合并請求](../../user/project/merge_requests/index.html) UI 中公開[作業工件](../pipelines/job_artifacts.html) . 例如，要匹配單個文件： ``` test: script: [ "echo 'test' > file.txt" ] artifacts: expose_as: 'artifact 1' paths: ['file.txt'] ``` 使用此配置，GitLab 會將鏈接**工件 1**添加到指向`file1.txt`的相關合并請求中. 匹配整個目錄的示例： ``` test: script: [ "mkdir test && echo 'test' > test/file.txt" ] artifacts: expose_as: 'artifact 1' paths: ['test/'] ``` 請注意以下幾點： * 使用變量定義`artifacts:paths`時，工件不會顯示在合并請求 UI 中. * 每個合并請求最多可以公開 10 個作業工件. * 不支持 glob 模式. * 如果指定了目錄，那么如果目錄中有多個文件，則該鏈接將指向作業[工件瀏覽器](../pipelines/job_artifacts.html#browsing-artifacts) . * 對于帶有`.html` ， `.htm` ， `.txt` ， `.json` ， `.xml`和`.log`擴展名的暴露的單個文件工件，如果[GitLab Pages](../../administration/pages/index.html)為： * 啟用后，GitLab 將自動渲染工件. * 未啟用，您將在工件瀏覽器中看到該文件. #### `artifacts:name`[](#artifactsname "Permalink") 在 GitLab 8.6 和 GitLab Runner v1.1.0 中引入. 通過`name`指令，您可以定義所創建的工件存檔的名稱. 這樣，您可以為每個檔案使用一個唯一的名稱，這在您要從 GitLab 下載檔案時很有用. `artifacts:name`變量可以使用任何[預定義變量](../variables/README.html) . 默認名稱是`artifacts` ，下載`artifacts`變為`artifacts.zip` . **注意：**如果您的分支名稱包含正斜杠（例如`feature/my-feature` ），建議使用`$CI_COMMIT_REF_SLUG`而不是`$CI_COMMIT_REF_NAME`來正確命名工件. 要使用當前作業的名稱創建檔案： ``` job: artifacts: name: "$CI_JOB_NAME" paths: - binaries/ ``` 要使用當前分支或標記的名稱（僅包括二進制文件目錄）創建檔案，請執行以下操作： ``` job: artifacts: name: "$CI_COMMIT_REF_NAME" paths: - binaries/ ``` 要使用當前作業的名稱和當前分支或標記（僅包括二進制文件目錄）創建檔案，請執行以下操作： ``` job: artifacts: name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME" paths: - binaries/ ``` 要創建一個具有當前[階段](#stages)名稱和分支名稱的檔案： ``` job: artifacts: name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME" paths: - binaries/ ``` * * * 如果使用**Windows Batch**運行 Shell 腳本，則需要將`$`替換`$` `%` ： ``` job: artifacts: name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%" paths: - binaries/ ``` 如果使用**Windows PowerShell**運行 Shell 腳本，則需要將`$`替換`$` `$env:` ：： ``` job: artifacts: name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME" paths: - binaries/ ``` #### `artifacts:untracked`[](#artifactsuntracked "Permalink") `artifacts:untracked`用于將所有 Git 未跟蹤的文件添加為工件（以及`artifacts:paths`定義的`artifacts:paths` ）. **Note:** `artifacts:untracked` ignores configuration in the repository’s `.gitignore` file. 發送所有未跟蹤的 Git 文件： ``` artifacts: untracked: true ``` 發送所有 Git 未跟蹤的文件和`binaries` ： ``` artifacts: untracked: true paths: - binaries/ ``` 發送所有未跟蹤的文件，但[不包括](#artifactsexclude) `*.txt` ： ``` artifacts: untracked: true exclude: - *.txt ``` #### `artifacts:when`[](#artifactswhen "Permalink") 在 GitLab 8.9 和 GitLab Runner v1.3.0 中引入. `artifacts:when`用于在作業失敗時或盡管失敗而上傳工件. 可以設置為以下值之一的`artifacts:when` ： 1. `on_success`僅在作業成功時才上傳工件. 這是默認值. 2. `on_failure`僅在作業失敗時上載工件. 3. `always` -上載工件，無論作業狀態如何. 要僅在作業失敗時上傳工件： ``` job: artifacts: when: on_failure ``` #### `artifacts:expire_in`[](#artifactsexpire_in "Permalink") 在 GitLab 8.9 和 GitLab Runner v1.3.0 中引入. `expire_in` allows you to specify how long artifacts should live before they expire and are therefore deleted, counting from the time they are uploaded and stored on GitLab. If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.html#default-artifacts-expiration-core-only) (30 days by default). 您可以使用作業頁面上的" **保留"**按鈕來覆蓋過期并永久保留工件. 過期后，默認情況下每小時（通過 cron 作業）刪除工件，并且不再可用. The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Examples of valid values: * `42` * `3 mins 4 sec` * `2 hrs 20 min` * `2h20min` * `6 mos 1 day` * `47 yrs 6 mos and 4d` * `3 weeks and 2 days` 要在上傳后 1 周內使工件過期： ``` job: artifacts: expire_in: 1 week ``` **注意：**對于在[GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/16267)和更高版本中創建的工件，無論有效時間如何，始終會保留引用的最新工件. #### `artifacts:reports`[](#artifactsreports "Permalink") [`artifacts:reports`關鍵字](../pipelines/job_artifacts.html#artifactsreports)用于從作業中收集測試報告，代碼質量報告和安全性報告. 它還在 GitLab 的 UI 中顯示這些報告（合并請求，管道視圖和安全性儀表板）. 這些是可用的報告類型： | Parameter | Description | | --- | --- | | [`artifacts:reports:junit`](../pipelines/job_artifacts.html#artifactsreportsjunit) | `junit`報告收集 JUnit XML 文件. | | [`artifacts:reports:dotenv`](../pipelines/job_artifacts.html#artifactsreportsdotenv) | `dotenv`報告收集一組環境變量. | | [`artifacts:reports:cobertura`](../pipelines/job_artifacts.html#artifactsreportscobertura) | `cobertura`報告收集 Co??bertura coverage XML 文件. | | [`artifacts:reports:terraform`](../pipelines/job_artifacts.html#artifactsreportsterraform) | `terraform`報告收集 Terraform `tfplan.json`文件. | | [`artifacts:reports:codequality`](../pipelines/job_artifacts.html#artifactsreportscodequality-starter) | `codequality`報告收集 Co??deQuality 問題. | | [`artifacts:reports:sast`](../pipelines/job_artifacts.html#artifactsreportssast-ultimate) | `sast`報告收集"靜態應用程序安全性測試"漏洞. | | [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.html#artifactsreportsdependency_scanning-ultimate) | `dependency_scanning`報告收集"依賴關系掃描"漏洞. | | [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.html#artifactsreportscontainer_scanning-ultimate) | `container_scanning`報告收集容器掃描漏洞. | | [`artifacts:reports:dast`](../pipelines/job_artifacts.html#artifactsreportsdast-ultimate) | `dast`報告收集動態應用程序安全測試漏洞. | | [`artifacts:reports:license_management`](../pipelines/job_artifacts.html#artifactsreportslicense_management-ultimate) | `license_management`報告收集許可證（ *已從 GitLab 13.0 中刪除* ）. | | [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.html#artifactsreportslicense_scanning-ultimate) | `license_scanning`報告收集許可證. | | [`artifacts:reports:performance`](../pipelines/job_artifacts.html#artifactsreportsperformance-premium) | `performance`報告收集績效指標. | | [`artifacts:reports:metrics`](../pipelines/job_artifacts.html#artifactsreportsmetrics-premium) | `metrics`報告收集指標. | #### `dependencies`[](#dependencies "Permalink") 在 GitLab 8.6 和 GitLab Runner v1.1.1 中引入. 默認情況下，所有先前[階段的](#stages)所有[`artifacts`](#artifacts)都被傳遞，但是您可以使用`dependencies`參數來定義要從中獲取工件的有限的作業列表（或沒有作業）. 要使用此功能，請在作業的上下文中定義`dependencies` ，并傳遞所有以前的工件應從中下載工件的列表. 您只能從當前階段之前執行的階段定義作業. 如果您從當前階段或下一個階段定義作業，將顯示錯誤. 定義一個空數組將跳過下載該作業的任何工件. 在使用`dependencies` ，不會考慮先前作業的狀態，因此，如果它失敗或它是未運行的手動作業，則不會發生錯誤. 在以下示例中，我們使用工件定義了兩個作業`build:osx`和`build:linux` . 當執行`test:osx` ，將在`build:osx`上下文中下載并提取來自`build:osx`的工件. `test:linux`和`build:linux`工件也發生了同樣的情況. 由于[階段](#stages)優先，作業`deploy`將下載所有先前作業的工件： ``` 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 ``` ##### When a dependent job will fail[](#when-a-dependent-job-will-fail "Permalink") 在 GitLab 10.3 中引入. 如果設置為依賴項的作業的工件已[過期](#artifactsexpire_in)或已[擦除](../pipelines/job_artifacts.html#erasing-artifacts) ，則依賴項作業將失敗. **注意：**您可以要求管理員[翻轉此開關](../../administration/job_artifacts.html#validation-for-dependencies)并恢復原來的行為. ### `coverage`[](#coverage "Permalink") 在 GitLab 8.17 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20428) . `coverage`允許您配置如何從作業輸出中提取代碼 coverage. 正則表達式是此處期望的唯一有效值. 因此，必須使用周圍的`/` ，以便一致且顯式表示正則表達式字符串. 如果要按字面意義匹配特殊字符，則必須轉義它們. 一個簡單的例子： ``` job1: script: rspec coverage: '/Code coverage: \d+\.\d+/' ``` ### `retry`[](#retry "Permalink") 版本歷史 * 在 GitLab 9.5 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) . * [行為](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515)在 GitLab 11.5 中進行了[擴展](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) ，以控制重試哪些失敗. `retry`允許您配置在失敗的情況下重試作業的次數. 當作業失敗并配置了`retry` ，它將再次處理，直到`retry`關鍵字指定的時間. 如果`retry`設置為 2，并且作業在第二次運行中成功（第一次重試），則不會再次重試. `retry`值必須是一個正整數，等于或大于 0，但小于或等于 2（最多兩次重試，總共運行 3 次）. 在所有失敗情況下重試的簡單示例： ``` test: script: rspec retry: 2 ``` 默認情況下，將在所有失敗情況下重試作業. 為了更好地控制重`retry`哪些失敗，重`retry`可以是具有以下鍵的哈希值： * `max` ：最大重試次數. * `when` ：失敗案例重試. 要最多僅重試運行程序系統故障兩次： ``` test: script: rspec retry: max: 2 when: runner_system_failure ``` 如果有其他故障，而不是運行器系統故障，則不會重試該作業. 重試對多個故障的情況下， `when`也可以是故障的數組： ``` test: script: rspec retry: max: 2 when: - runner_system_failure - stuck_or_timeout_failure ``` `when`可能值為： * `always` ：發生任何故障時重試（默認）. * `unknown_failure` ：當失敗原因未知時重試. * `script_failure` ：腳本失敗時重試. * `api_failure` ：API 失敗重試. * `stuck_or_timeout_failure` ：作業卡住或超時時重試. * `runner_system_failure` ：如果運行系統發生故障（例如，作業設置失敗），請重試. * `missing_dependency_failure` ：如果缺少依賴項，請重試. * `runner_unsupported` ：如果跑步者不受支持，請重試. * `stale_schedule` ：如果無法執行延遲的作業，請重試. * `job_execution_timeout` ：如果腳本超出了為作業設置的最大執行時間，則重試. * `archived_failure` ：如果作業已存檔且無法運行，請重試. * `unmet_prerequisites` ：如果作業未能完成先決條件任務，請重試. * `scheduler_failure` ：如果調度程序未能將作業分配給運行`scheduler_failure`重試. * `data_integrity_failure` ：如果檢測到結構完整性問題，請重試. 您可以使用變量指定[作業執行某些階段的重試次數](#job-stages-attempts) . ### `timeout`[](#timeout "Permalink") 在 GitLab 12.3 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) . `timeout`允許您為特定作業配置超時. 例如： ``` build: script: build.sh timeout: 3 hours 30 minutes test: script: rspec timeout: 3h 30m ``` 作業級超時可以超過[項目級超時，](../pipelines/settings.html#timeout)但不能超過 Runner 特定的超時. ### `parallel`[](#parallel "Permalink") 在 GitLab 11.5 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) . `parallel`允許您配置要并行運行的作業實例數. 此值必須大于或等于兩（2）并且小于或等于 50. 這將創建 N 個并行運行的同一作業實例. 它們從`job_name 1/N`到`job_name N/N`依次命名. 對于每個作業， `CI_NODE_INDEX`設置`CI_NODE_INDEX`和`CI_NODE_TOTAL` [環境變量](../variables/README.html#predefined-environment-variables) . 標記要并行運行的作業需要將`parallel`添加到配置文件中. 例如： ``` test: script: rspec parallel: 5 ``` **提示：**跨并行作業并行測試套件. 不同的語言具有不同的工具來促進這一點. 一個使用[信號量測試助推器](https://github.com/renderedtext/test-boosters)和 RSpec 來運行一些 Ruby 測試的簡單示例： ``` # Gemfile source 'https://rubygems.org' gem 'rspec' gem 'semaphore_test_boosters' ``` ``` test: parallel: 3 script: - bundle - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL ``` **警告：**請注意 semaphore_test_boosters 向作者報告使用情況統計信息. 然后，您可以導航到新管道構建的" **作業"**選項卡，并查看 RSpec 作業分為三個單獨的作業. ### `trigger`[](#trigger "Permalink") 版本歷史 * 在[GitLab Premium](https://about.gitlab.com/pricing/) 11.8 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) . * 在 12.8 中[移至](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) GitLab Core. `trigger`允許您定義下游管道觸發器. 當 GitLab 從`trigger`定義創建的作業啟動時，將創建一個下游管道. 此關鍵字允許創建兩種不同類型的下游管道： * [Multi-project pipelines](../multi_project_pipelines.html#creating-multi-project-pipelines-from-gitlab-ciyml) * [Child pipelines](../parent_child_pipelines.html) **注意：**將`trigger`與`when:manual`一起使用會導致錯誤`jobs:#{job-name} when should be on_success, on_failure or always` ，因為`when:manual`阻止使用觸發器. #### Simple `trigger` syntax for multi-project pipelines[](#simple-trigger-syntax-for-multi-project-pipelines "Permalink") 配置下游觸發器的最簡單方法是使用帶有指向下游項目的完整路徑的`trigger`關鍵字： ``` rspec: stage: test script: bundle exec rspec staging: stage: deploy trigger: my/deployment ``` #### Complex `trigger` syntax for multi-project pipelines[](#complex-trigger-syntax-for-multi-project-pipelines "Permalink") 可以配置分支名稱，GitLab 將使用該分支名稱來創建下游管道： ``` rspec: stage: test script: bundle exec rspec staging: stage: deploy trigger: project: my/deployment branch: stable ``` 可以從觸發的管道中鏡像狀態： ``` trigger_job: trigger: project: my/project strategy: depend ``` 可以從上游管道鏡像狀態： ``` upstream_bridge: stage: test needs: pipeline: other/project ``` #### `trigger` syntax for child pipeline[](#trigger-syntax-for-child-pipeline "Permalink") 在 GitLab 12.7 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) . 要創建[子管道](../parent_child_pipelines.html) ，請指定包含子管道的 CI 配置的 YAML 文件的路徑： ``` trigger_job: trigger: include: path/to/child-pipeline.yml ``` 類似于[多項目管道](../multi_project_pipelines.html#mirroring-status-from-triggered-pipeline) ，可以從觸發的管道中鏡像狀態： ``` trigger_job: trigger: include: - local: path/to/child-pipeline.yml strategy: depend ``` ##### Trigger child pipeline with generated configuration file[](#trigger-child-pipeline-with-generated-configuration-file "Permalink") 在 GitLab 12.9 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) . 您還可以從[動態生成的配置文件](../parent_child_pipelines.html#dynamic-child-pipelines)觸發子管道： ``` generate-config: stage: build script: generate-ci-config > generated-config.yml artifacts: paths: - generated-config.yml child-pipeline: stage: test trigger: include: - artifact: generated-config.yml job: generate-config ``` 從工件中提取了`generated-config.yml` ，并用作觸發子管道的配置. #### Linking pipelines with `trigger:strategy`[](#linking-pipelines-with-triggerstrategy "Permalink") 默認情況下，一旦創建下游管道， `trigger`作業就會以`success`狀態完成. 要強制`trigger`作業等待下游（多項目或子項目）管道完成，請使用`strategy: depend` . 這將使觸發作業以"運行"狀態等待，直到觸發的管道完成. 此時， `trigger`作業將完成并顯示與下游作業相同的狀態. ``` trigger_job: trigger: include: path/to/child-pipeline.yml strategy: depend ``` 這可以使您的管道執行保持線性. 在上面的示例中，后續階段的作業將在啟動之前等待觸發的管道成功完成，但代價是并行化程度降低. #### Trigger a pipeline by API call[](#trigger-a-pipeline-by-api-call "Permalink") 當使用觸發器令牌創建管道時，觸發器可以用于通過 API 調用強制重建特定的分支，標記或提交. 不要與[`trigger`](#trigger)參數混淆. [Read more in the triggers documentation.](../triggers/README.html) ### `interruptible`[](#interruptible "Permalink") 在 GitLab 12.3 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) . `interruptible`可用于指示如果作業因新的管道運行而變得多余，則應取消該作業. 默認為`false` . 僅當啟用了[自動取消冗余管道功能](../pipelines/settings.html#auto-cancel-pending-pipelines)時，才使用此值. 啟用后，在以下情況下，將取消同一分支上的管道： * 它通過新的管道運行而變得多余. * 將所有作業都設置為可中斷，或者尚未開始任何不間斷的作業. 待處理的作業始終被視為可中斷的. **Tip:** Set jobs as interruptible that can be safely canceled once started (for instance, a build job). 這是一個簡單的示例： ``` stages: - stage1 - stage2 - stage3 step-1: stage: stage1 script: - echo "Can be canceled." interruptible: true step-2: stage: stage2 script: - echo "Can not be canceled." step-3: stage: stage3 script: - echo "Because step-2 can not be canceled, this step will never be canceled, even though set as interruptible." interruptible: true ``` 在上面的示例中，新的管道運行將導致現有的正在運行的管道為： * 如果僅`step-1`正在運行或掛起，則取消. * 一旦`step-2`開始運行，則不會取消. **注意：**一旦運行了不間斷的作業，無論最終作業的狀態如何，管道將永遠不會被取消. ### `resource_group`[](#resource_group "Permalink") 在 GitLab 12.7 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) . 有時在環境中同時運行多個作業或管道可能會導致在部署過程中出錯. 為了避免這些錯誤，可以使用`resource_group`屬性來確保 Runner 不會同時運行某些作業. 當在`.gitlab-ci.yml`為作業定義了`resource_group`鍵時，作業執行在同一項目的不同管道之間是互斥的. 如果屬于同一資源組的多個作業同時進入隊列，則 Runner 將僅選擇一個作業，其他作業將等待，直到`resource_group`空閑為止. 這是一個簡單的示例： ``` deploy-to-production: script: deploy resource_group: production ``` 在這種情況下，如果`deploy-to-production`作業在管道運行，并且新的`deploy-to-production`中不同的管道創建工作，它不會運行，直到當前運行的/未決`deploy-to-production`工作完成. 結果，您可以確保并發部署永遠不會在生產環境中發生. 每個環境可以定義多個`resource_group` . 一個很好的用例是在部署到物理設備時. 您可能具有多個物理設備，并且每個物理設備都可以部署到其中，但是在任何給定時間，每個設備只能有一個部署. **注：**此鍵只能包含字母，數字， `-` `_` ， `/` ， `$` ， `{` ， `}` ， `.` 和空格. 它不能以`/`開頭或結尾. 有關更多信息，請參見[部署安全](../environments/deployment_safety.html) . ### `release`[](#release "Permalink") 在 GitLab 13.2 中[引入](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) . `release`表示作業創建一個[Release](../../user/project/releases/index.html) ，并且可以選擇包含 Release 資產的 URL. 支持以下方法： * [`tag_name`](#releasetag_name) * [`name`](#releasename) (optional) * [`description`](#releasedescription) (optional) * [`ref`](#releaseref) (optional) * [`milestones`](#releasemilestones) (optional) * [`released_at`](#releasereleased_at) (optional) 僅當作業處理沒有錯誤時才創建發布. 如果 Rails API 在發布創建期間返回錯誤，則`release`作業將失敗. #### `release-cli` Docker image[](#release-cli-docker-image "Permalink") 必須使用以下指令指定用于`release-cli`的 Docker 映像： ``` image: registry.gitlab.com/gitlab-org/release-cli:latest ``` #### Script[](#script-1 "Permalink") 所有作業至少需要一個`script`標簽. `:release`作業可以使用`:script`標記的輸出，但是如果沒有必要，則可以使用占位符腳本，例如： ``` script: - echo 'release job' ``` 在即將發布的 GitLab 版本中存在刪除此要求的[問題](https://gitlab.com/gitlab-org/gitlab/-/issues/223856) . 管道可以具有多個`release`作業，例如： ``` ios-release: script: - echo 'iOS release job' release: tag_name: v1.0.0-ios description: 'iOS release v1.0.0' android-release: script: - echo 'Android release job' release: tag_name: v1.0.0-android description: 'Android release v1.0.0' ``` #### `release:tag_name`[](#releasetag_name "Permalink") 必須指定`tag_name` . 它可以引用現有的 Git 標記，也可以由用戶指定. 當存儲庫中不存在指定的標簽時，將從管道的關聯 SHA 創建一個新標簽. 例如，從 Git 標簽創建 Release 時： ``` job: release: tag_name: $CI_COMMIT_TAG description: changelog.txt ``` 也可以創建任何唯一標簽， `only: tags`在這種情況下`only: tags`不是必需的. 語義版本控制示例： ``` job: release: tag_name: ${MAJOR}_${MINOR}_${REVISION} description: changelog.txt ``` * 僅當作業的主腳本成功時才創建發布. * 如果版本已經存在，則不會更新，并且帶有`release`關鍵字的作業將失敗. * `release`部分在`script`標記之后和`after_script`之前`after_script` . #### `release:name`[](#releasename "Permalink") 發布名稱. 如果省略，則使用`release: tag_name`的值填充`release: tag_name` . #### `release:description`[](#releasedescription "Permalink") 指定發布的詳細描述. #### `release:ref`[](#releaseref "Permalink") 如果`release: tag_name`尚不存在，則從`ref`創建版本. `ref`可以是提交 SHA，其他標記名稱或分支名稱. #### `release:milestones`[](#releasemilestones "Permalink") 與發行版關聯的每個里程碑的標題. #### `release:released_at`[](#releasereleased_at "Permalink") 發布準備就緒的日期和時間. 如果未定義，則默認為當前日期和時間. 預期為 ISO 8601 格式（2019-03-15T08：00：00Z）. #### Complete example for `release`[](#complete-example-for-release "Permalink") 結合上面給出的`release`示例，將產生以下代碼段. 有兩種選擇，具體取決于生成標記的方式. 這些選項不能一起使用，因此請選擇以下一種： * 要在按下 Git 標簽或在 UI 中通過添加**存儲庫>標簽**來添加 Git 標簽時創建發行版： ``` release_job: stage: release image: registry.gitlab.com/gitlab-org/release-cli:latest rules: - if: $CI_COMMIT_TAG # Run this job when a tag is created manually script: - echo 'running release_job' release: name: 'Release $CI_COMMIT_TAG' description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline. ref: '$CI_COMMIT_TAG' milestones: - 'm1' - 'm2' - 'm3' released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, # or can use a variable. ``` * 要使用更改定義的新 Git 標簽，將更改推送到默認分支時自動創建發行版： ``` release_job: stage: release image: registry.gitlab.com/gitlab-org/release-cli:latest rules: - if: $CI_COMMIT_TAG when: never # Do not run this job when a tag is created manually - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when the default branch changes script: - echo 'running release_job' release: name: 'Release $CI_COMMIT_SHA' description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the tag_name tag_name: 'v${MAJOR}.${MINOR}.${REVISION}' # variables must be defined elsewhere ref: '$CI_COMMIT_SHA' # in the pipeline. milestones: - 'm1' - 'm2' - 'm3' released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, # or can use a variable. ``` #### `releaser-cli` command line[](#releaser-cli-command-line "Permalink") `:release`節點下的條目被轉換為`bash`命令行，并發送到包含[release-cli](https://gitlab.com/gitlab-org/release-cli)的 Docker 容器. 您也可以直接從`script`條目調用`release-cli` . 上面描述的 YAML 將被翻譯成如下的 CLI 命令： ``` release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" ``` ### `pages`[](#pages "Permalink") `pages`是一項特殊的工作，用于將靜態內容上傳到 GitLab，可用于為您的網站提供服務. 它具有特殊的語法，因此必須滿足以下兩個要求： * 任何靜態內容都必須放在`public/`目錄下. * 必須定義帶有`public/`目錄路徑的`artifacts` . 下面的示例只是將所有文件從項目的根目錄移到`public/`目錄. `.public`解決方法是，因此`cp`也不會在無限循環中將`public/`復制到自身： ``` pages: stage: deploy script: - mkdir .public - cp -r * .public - mv .public public artifacts: paths: - public only: - master ``` 閱讀有關[GitLab Pages 用戶文檔的](../../user/project/pages/index.html)更多[信息](../../user/project/pages/index.html) . ## `variables`[](#variables "Permalink") 在 GitLab Runner v0.5.0 中引入. **注意：**對于變量的名稱和值，整數（以及字符串）都是合法的. 浮動廣告不合法，不能使用. GitLab CI / CD 允許您在`.gitlab-ci.yml`中定義變量，然后在作業環境中傳遞這些變量. 它們可以全局設置，也可以按工作設置. 在作業級別上使用`variables`關鍵字時，它將覆蓋全局 YAML 變量和相同名稱的預定義變量. 它們存儲在 Git 存儲庫中，用于存儲非敏感項目配置，例如： ``` variables: DATABASE_URL: "postgres://postgres@postgres/my_database" ``` 這些變量以后可以在所有執行的命令和腳本中使用. YAML 定義的變量也設置為所有創建的服務容器，從而允許對其進行微調. 除了用戶定義的變量外，還有[由 Runner 本身設置的](../variables/README.html#predefined-environment-variables)變量. 一個示例是`CI_COMMIT_REF_NAME` ，它具有為其構建項目的分支或標記名稱的值. 除了可以在`.gitlab-ci.yml`設置的變量`.gitlab-ci.yml` ，還有可以在 GitLab 的 UI 中設置的所謂[變量](../variables/README.html#gitlab-cicd-environment-variables) . 提供了[用于變量的 YAML 錨](#yaml-anchors-for-variables) . 了解有關[變量及其優先級的](../variables/README.html)更多信息. ### Git strategy[](#git-strategy "Permalink") 版本歷史 * 在 GitLab 8.9 中作為實驗功能引入. * `GIT_STRATEGY=none`要求 GitLab Runner `GIT_STRATEGY=none` +. **注意：**在將來的版本中可能會更改或完全刪除. 您可以在[`variables`](#variables)部分中全局或按作業設置用于獲取最新應用程序代碼的`GIT_STRATEGY` . 如果未指定，將使用項目設置中的默認設置. 有三個可能的值： `clone` ， `fetch`和`none` . `clone`是最慢的選擇. 它為每個作業從頭克隆存儲庫，以確保本地工作副本始終是原始的. ``` variables: GIT_STRATEGY: clone ``` `fetch`速度更快，因為它可以重新使用本地工作副本（如果不存在則回退到`clone` ）. `git clean`用于撤消上一個作業所做的任何更改，而`git fetch`用于檢索自上一個作業運行以來進行的提交. ``` variables: GIT_STRATEGY: fetch ``` `none`再使用本地工作副本，但是會跳過所有 Git 操作（包括 GitLab Runner 的預克隆腳本（如果存在））. 對于僅在工件上運行的作業（例如`deploy` ），它最有用. Git 存儲庫數據可能存在，但是肯定會過時，因此您應該僅依靠從緩存或工件導入本地工作副本的文件. ``` variables: GIT_STRATEGY: none ``` **注意：** `GIT_STRATEGY`器不支持[GIT_STRATEGY](https://docs.gitlab.com/runner/executors/kubernetes.html) ，但將來可能會支持. 有關更新，請參閱[帶有 Kubernetes 執行器功能建議](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847)的[支持 Git 策略](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847) . ### Git submodule strategy[](#git-submodule-strategy "Permalink") > 需要 GitLab Runner v1.10 +. `GIT_SUBMODULE_STRATEGY`變量用于控制在構建之前獲取代碼時是否包含/如何包含 Git 子模塊. 您可以在[`variables`](#variables)部分中全局或按作業設置它們. 共有三個可能的值： `none` ， `normal`和`recursive` ： * `none`表示在獲取項目代碼時將不包含子模塊. 這是默認設置，與 v1.10 之前的行為匹配. * `normal`意味著僅包括頂級子模塊. 等效于： ``` git submodule sync git submodule update --init ``` * `recursive`意味著將包括所有子模塊（包括子模塊的子模塊）. 此功能需要 Git v1.8.1 及更高版本. 當將 GitLab Runner 與不基于 Docker 的執行器一起使用時，請確保 Git 版本符合該要求. 等效于： ``` git submodule sync --recursive git submodule update --init --recursive ``` 請注意，為使此功能正常工作，必須使用以下任一方式（在`.gitmodules` ）配置子模塊： * 可公開訪問的存儲庫的 HTTP（S）URL，或者 * 到同一 GitLab 服務器上另一個存儲庫的相對路徑. 請參閱[Git 子模塊](../git_submodules.html)文檔. ### Git checkout[](#git-checkout "Permalink") 在 GitLab Runner 9.3 中引入. 當`GIT_STRATEGY`設置為`clone`或`fetch`以指定是否應運行`git checkout`時，可以使用`GIT_CHECKOUT`變量. 如果未指定，則默認為 true. 您可以在[`variables`](#variables)部分中全局或按作業設置它們. 如果設置為`false` ，則跑步者將： * 進行`fetch` -更新存??儲庫，并將工作副本保留在當前版本中， * 執行`clone` -克隆存儲庫，并將工作副本保留在默認分支上. 將此設置設置為`true`意味著對于`clone`和`fetch`策略，Runner 將簽出工作副本到與 CI 管道相關的修訂版本： ``` variables: GIT_STRATEGY: clone GIT_CHECKOUT: "false" script: - git checkout -B master origin/master - git merge $CI_COMMIT_SHA ``` ### Git clean flags[](#git-clean-flags "Permalink") 在 GitLab Runner 11.10 中引入 `GIT_CLEAN_FLAGS`變量用于在簽出源代碼后控制`git clean`的默認行為. 您可以在[`variables`](#variables)部分中全局設置或按作業設置. `GIT_CLEAN_FLAGS`接受[`git clean`](https://git-scm.com/docs/git-clean)命令的所有可能選項. 如果指定了`GIT_CHECKOUT: "false"`則禁用`git clean` . If `GIT_CLEAN_FLAGS` is: * 未指定， `git clean`標志默認為`-ffdx` . * 給定值`none` ，將不執行`git clean` . 例如： ``` variables: GIT_CLEAN_FLAGS: -ffdx -e cache/ script: - ls -al cache/ ``` ### Git fetch extra flags[](#git-fetch-extra-flags "Permalink") 在 GitLab Runner 13.1 中[引入](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) . `GIT_FETCH_EXTRA_FLAGS`變量用于控制`git fetch`的行為. 您可以在[`variables`](#variables)部分中全局設置或按作業設置. `GIT_FETCH_EXTRA_FLAGS`接受[`git fetch`](https://git-scm.com/docs/git-fetch)命令的所有可能選項，但請注意， `GIT_FETCH_EXTRA_FLAGS`標志將附加在無法修改的默認標志之后. 默認標志是： * [GIT_DEPTH](#shallow-cloning). * [refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec)列表. * 遙遠的`origin` . If `GIT_FETCH_EXTRA_FLAGS` is: * 未指定， `git fetch`標志與默認標志一起默認為`--prune --quiet` . * 給定值`none` ，僅使用默認標志執行`git fetch` . 例如，默認標志是`--prune --quiet` ，因此您可以通過僅用`--prune`覆蓋它來使`git fetch`更加詳細： ``` variables: GIT_FETCH_EXTRA_FLAGS: --prune script: - ls -al cache/ ``` 上面的配置將導致以這種方式調用`git fetch` ： ``` git fetch origin $REFSPECS --depth 50 --prune ``` 其中`$REFSPECS`是 GitLab 內部提供給 Runner 的值. ### Job stages attempts[](#job-stages-attempts "Permalink") 在 GitLab 中引入，它需要 GitLab Runner v1.9 +. 您可以設置正在運行的作業嘗試執行以下每個階段的嘗試次數： | Variable | Description | | --- | --- | | **GET_SOURCES_ATTEMPTS** | 嘗試獲取運行作業的源的次數 | | **ARTIFACT_DOWNLOAD_ATTEMPTS** | 嘗試下載運行作業的工件的次數 | | **RESTORE_CACHE_ATTEMPTS** | 還原運行作業的緩存的嘗試次數 | | **EXECUTOR_JOB_SECTION_ATTEMPTS** | [從 GitLab 12.10 開始](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) ，出現[`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450)錯誤（僅限[Docker 執行器](https://docs.gitlab.com/runner/executors/docker.html) ）后，嘗試在作業中運行部分的次數. | 默認為一次嘗試. Example: ``` variables: GET_SOURCES_ATTEMPTS: 3 ``` 您可以在[`variables`](#variables)部分中全局或按作業設置它們. ### Shallow cloning[](#shallow-cloning "Permalink") 在 GitLab 8.9 中作為實驗功能引入. **注意** ：從 GitLab 12.0 開始，新創建的項目將自動具有[默認的`git depth`值`50`](../pipelines/settings.html#git-shallow-clone) . 您可以使用`GIT_DEPTH`指定獲取和克隆的深度. 這允許對存儲庫進行淺層克隆，從而可以顯著加快克隆具有大量提交或舊的大型二進制文件的存儲庫. 該值傳遞給`git fetch`和`git clone` . **注意：**如果使用 1 的深度，并且有作業隊列或重試作業，則作業可能會失敗. 由于 Git 的獲取和克隆基于引用（例如分支名稱），因此 Runners 無法克隆特定的提交 SHA. 如果隊列中有多個作業，或者您要重試舊的作業，則要測試的提交必須在克隆的 Git 歷史記錄內. 如果為`GIT_DEPTH`設置的值`GIT_DEPTH`則無法運行這些舊的提交. 您將在作業日志中看到`unresolved reference` . 然后，您應該重新考慮將`GIT_DEPTH`更改為更高的值. 設置`GIT_DEPTH`時，依賴`git describe`作業可能無法正常工作，因為僅存在一部分 Git 歷史記錄. 要僅獲取或克隆最后 3 個提交，請執行以下操作： ``` variables: GIT_DEPTH: "3" ``` 您可以在[`variables`](#variables)部分中全局設置或按作業設置. ### Custom build directories[](#custom-build-directories "Permalink") 在 GitLab Runner 11.10 中[引入](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) **注意：**僅當在[Runner 的配置中](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)啟用`custom_build_dir`時，才可以使用此`custom_build_dir` . 這是默認配置`docker`和`kubernetes`執行. 默認情況下，GitLab Runner 將存儲`$CI_BUILDS_DIR`到`$CI_BUILDS_DIR`目錄的唯一子路徑中. 但是，您的項目可能需要特定目錄中的代碼（例如，Go 項目）. 在這種情況下，您可以指定`GIT_CLONE_PATH`變量，以告知 Runner 在哪個目錄中克隆存儲庫： ``` variables: GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name test: script: - pwd ``` `GIT_CLONE_PATH`必須始終在`$CI_BUILDS_DIR` . `$CI_BUILDS_DIR`設置的目錄取決于執行程序和[runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)設置的配置. #### Handling concurrency[](#handling-concurrency "Permalink") 使用并發性大于`1`的執行程序可能會導致失敗，因為如果在作業之間共享`builds_dir`則多個作業可能在同一目錄上工作. GitLab Runner 不會嘗試防止這種情況. 管理員和開發人員必須遵守 Runner 配置的要求. 為了避免這種情況，您可以在`$CI_BUILDS_DIR`內使用唯一路徑，因為 Runner 公開了兩個提供唯一并發`ID`的變量： * `$CI_CONCURRENT_ID` ：給定執行程序中運行的所有作業的唯一 ID. * `$CI_CONCURRENT_PROJECT_ID` ：給定執行程序和項目中運行的所有作業的唯一 ID. 在任何情況下以及在任何執行程序上都應能正常工作的最穩定的配置是在`$CI_CONCURRENT_ID`中使用`$CI_CONCURRENT_ID` `GIT_CLONE_PATH` . 例如： ``` variables: GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name test: script: - pwd ``` 在`$CI_CONCURRENT_PROJECT_ID`應結合使用`$CI_PROJECT_PATH`為`$CI_PROJECT_PATH`提供了一個存儲庫的路徑. 即`group/subgroup/project` . 例如： ``` variables: GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH test: script: - pwd ``` #### Nested paths[](#nested-paths "Permalink") `GIT_CLONE_PATH`的值被擴展一次，并且不支持其中的嵌套變量. 例如，您在`.gitlab-ci.yml`文件中定義以下兩個變量： ``` variables: GOPATH: $CI_BUILDS_DIR/go GIT_CLONE_PATH: $GOPATH/src/namespace/project ``` `GIT_CLONE_PATH`的值一次擴展到`$CI_BUILDS_DIR/go/src/namespace/project` ，并且由于`$CI_BUILDS_DIR`沒有擴展而導致失敗. ## Special YAML features[](#special-yaml-features "Permalink") 可以使用特殊的 YAML 功能，例如錨點（ `&` ），別名（ `*` ）和地圖合并（ `<<` ），這將使您大大降低`.gitlab-ci.yml`的復雜性. 閱讀有關各種[YAML 功能的](https://learnxinyminutes.com/docs/yaml/)更多信息. 在大多數情況下， [`extends`關鍵字](#extends)更加用戶友好，應該在這些特殊的 YAML 功能上使用. 可能仍需要使用 YAML 錨來合并數組. ### Anchors[](#anchors "Permalink") 在 GitLab 8.6 和 GitLab Runner v1.1.1 中引入. YAML 具有稱為"錨"的便捷功能，使您可以輕松地在整個文檔中復制內容. 錨可用于復制/繼承屬性，并且是與[隱藏作業](#hide-jobs)一起使用以為您的作業提供模板的完美示例. 當有重復的密鑰時，GitLab 將基于密鑰執行反向深度合并. 以下示例使用錨點和地圖合并. 它將創建兩個作業`test1`和`test2` ，它們將繼承`.job_template`的參數，每個參數都定義了自己的自定義`script` ： ``` .job_template: &job_definition # Hidden key that defines an anchor named 'job_definition' image: ruby:2.6 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 ``` `&`設置錨點的名稱（ `job_definition` ）， `<<`表示"將給定的哈希值合并到當前哈希中"，并且`*`包括命名的錨點（再次為`job_definition` ）. 擴展版本如下所示： ``` .job_template: image: ruby:2.6 services: - postgres - redis test1: image: ruby:2.6 services: - postgres - redis script: - test1 project test2: image: ruby:2.6 services: - postgres - redis script: - test2 project ``` 讓我們來看另一個例子. 這次，我們將使用錨來定義兩組服務. 這將創建兩個作業： `test:postgres`和`test:mysql` ，它們將共享`.job_template`定義的`script`指令以及`.postgres_services`和`.mysql_services`定義的`services`指令： ``` .job_template: &job_definition script: - test project tags: - dev .postgres_services: services: &postgres_definition - postgres - ruby .mysql_services: services: &mysql_definition - mysql - ruby test:postgres: <<: *job_definition services: *postgres_definition tags: - postgres test:mysql: <<: *job_definition services: *mysql_definition ``` 擴展版本如下所示： ``` .job_template: script: - test project tags: - dev .postgres_services: services: - postgres - ruby .mysql_services: services: - mysql - ruby test:postgres: script: - test project services: - postgres - ruby tags: - postgres test:mysql: script: - test project services: - mysql - ruby tags: - dev ``` 您可以看到隱藏的作業可以方便地用作模板. **Note:** Note that `tags: [dev]` has been overwritten by `tags: [postgres]`.**注意：**利用[`include`](#include)功能時，不能在多個文件中使用 YAML 錨. 錨僅在定義它們的文件內有效.您可以使用[`extends`關鍵字](#extends)來代替使用 YAML 錨. #### YAML anchors for `before_script` and `after_script`[](#yaml-anchors-for-before_script-and-after_script "Permalink") 在 GitLab 12.5 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) . 您可以將[YAML 定位](#anchors) `after_script`與`before_script`和`after_script` ，從而可以在多個作業中包括預定義的命令列表. Example: ``` .something_before: &something_before - echo 'something before' .something_after: &something_after - echo 'something after' - echo 'another thing after' job_name: before_script: - *something_before script: - echo 'this is the script' after_script: - *something_after ``` #### YAML anchors for `script`[](#yaml-anchors-for-script "Permalink") 在 GitLab 12.5 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/23005) . 您可以將[YAML 錨點](#anchors)與腳本一起使用，從而可以在多個作業中包括預定義的命令列表. 例如： ``` .something: &something - echo 'something' job_name: script: - *something - echo 'this is the script' ``` #### YAML anchors for variables[](#yaml-anchors-for-variables "Permalink") [YAML 錨](#anchors)可以與`variables`一起使用，以輕松地在多個作業之間重復分配變量. 當作業需要特定的`variables`塊（否則將覆蓋全局變量）時，它還可以提供更大的靈活性. 在下面的示例中，我們將覆蓋`GIT_STRATEGY`變量，而不會影響`SAMPLE_VARIABLE`變量的使用： ``` # global variables variables: &global-variables SAMPLE_VARIABLE: sample_variable_value ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value # a job that needs to set the GIT_STRATEGY variable, yet depend on global variables job_no_git_strategy: stage: cleanup variables: <<: *global-variables GIT_STRATEGY: none script: echo $SAMPLE_VARIABLE ``` ### Hide jobs[](#hide-jobs "Permalink") 在 GitLab 8.6 和 GitLab Runner v1.1.1 中引入. 如果要臨時"禁用"作業，而不是注釋掉定義作業的所有行： ``` #hidden_job: # script: # - run test ``` 您可以改為以點號（ `.` ）開頭，GitLab CI / CD 不會對其進行處理. 在以下示例中， `.hidden_job`將被忽略： ``` .hidden_job: script: - run test ``` 使用此功能可忽略作業，或使用[特殊的 YAML 功能](#special-yaml-features)并將隱藏的作業轉換為模板. ## Skip Pipeline[](#skip-pipeline "Permalink") 如果您的提交消息包含`[ci skip]`或`[skip ci]` ，則使用大寫字母將創建提交，但是將跳過管道. 或者，如果使用 Git 2.10 或更高版本，則可以傳遞`ci.skip` [Git 推送選項](../../user/project/push_options.html#push-options-for-gitlab-cicd) . ## Processing Git pushes[](#processing-git-pushes "Permalink") 當在單個`git push`調用中推送多個更改時，GitLab 將最多創建 4 條分支和標簽管道. 此限制不影響任何更新的合并請求管道. 使用[合并請求](../merge_request_pipelines/index.html)管道時，所有更新的合并請求都將創建一個管道. ## Deprecated parameters[](#deprecated-parameters "Permalink") 不推薦使用以下參數. ### Globally-defined `types`[](#globally-defined-types "Permalink") **不**推薦**使用：** `types`不推薦使用，可以在以后的版本中刪除. 使用[`stages`](#stages)代替. ### Job-defined `type`[](#job-defined-type "Permalink") **不**推薦**使用：** `type`不推薦使用，可以在將來的發行版之一中將其刪除. 使用[`stage`](#stage)代替. ### Globally-defined `image`, `services`, `cache`, `before_script`, `after_script`[](#globally-defined-image-services-cache-before_script-after_script "Permalink") 不`after_script`全局定義`image` ， `services` ， `cache` ， `before_script`和`after_script` . 支持可以從將來的版本中刪除. 使用[`default:`](#global-defaults)代替. 例如： ``` default: image: ruby:2.5 services: - docker:dind cache: paths: [vendor/] before_script: - bundle install --path vendor/ after_script: - rm -rf tmp/ ```