diff options
Diffstat (limited to 'doc/ci')
| -rw-r--r-- | doc/ci/README.md | 1 | ||||
| -rw-r--r-- | doc/ci/environments.md | 39 | ||||
| -rw-r--r-- | doc/ci/introduction/index.md | 1 | ||||
| -rw-r--r-- | doc/ci/multi_project_pipelines.md | 11 | ||||
| -rw-r--r-- | doc/ci/variables/README.md | 16 | ||||
| -rw-r--r-- | doc/ci/variables/deprecated_variables.md | 7 | ||||
| -rw-r--r-- | doc/ci/variables/predefined_variables.md | 4 | ||||
| -rw-r--r-- | doc/ci/variables/where_variables_can_be_used.md | 4 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 60 |
9 files changed, 118 insertions, 25 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md index 27bde2ac0f1..93b82a065b3 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,6 +1,7 @@ --- comments: false description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset to build, test, and deploy your application." +type: index --- # GitLab CI/CD diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 5a14ac17aec..9f930833093 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Environments and deployments > Introduced in GitLab 8.9. @@ -667,9 +671,24 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scoping environments with specs **[PREMIUM]** -Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can -behave differently for each environment. For example, you can -[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables-premium). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. + +You can limit the environment scope of a variable by +defining which environments it can be available for. + +Wildcards can be used, and the default environment scope is `*`, which means +any jobs will have this variable, not matter if an environment is defined or +not. + +For example, if the environment scope is `production`, then only the jobs +having the environment `production` defined would have this specific variable. +Wildcards (`*`) can be used along with the environment name, therefore if the +environment scope is `review/*` then any jobs with environment names starting +with `review/` would have that particular variable. + +Some GitLab features can behave differently for each environment. +For example, you can +[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables-premium). **[PREMIUM]** In most cases, these features use the _environment specs_ mechanism, which offers an efficient way to implement scoping within each environment group. @@ -693,7 +712,7 @@ Each environment can be matched with the following environment spec: As you can see, you can use specific matching for selecting a particular environment, and also use wildcard matching (`*`) for selecting a particular environment group, -such as [Review apps](review_apps/index.md) (`review/*`). +such as [Review Apps](review_apps/index.md) (`review/*`). NOTE: **Note:** The most _specific_ spec takes precedence over the other wildcard matching. @@ -712,3 +731,15 @@ Below are some links you may find interesting: - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) - [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md) - [Deploy Boards for your applications running on Kubernetes](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]** + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index 0045fa2fb1f..bd2b9b099f2 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -1,5 +1,6 @@ --- description: "An overview of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD." +type: concepts --- # Introduction to CI/CD with GitLab diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 57825982ede..1091129a9dc 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -138,14 +138,15 @@ staging: The `ENVIRONMENT` variable will be passed to every job defined in a downstream pipeline. It will be available as an environment variable when GitLab Runner picks a job. -In the following configuration, the `MY_VARIABLE` variable will be passed -downstream, because jobs inherit variables declared in top-level `variables`: +In the following configuration, the `MY_VARIABLE` variable will be passed to the downstream pipeline +that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream` +job inherits variables declared in global variables blocks, and then we pass these variables to a downstream pipeline. ```yaml variables: MY_VARIABLE: my-value -my-pipeline: +trigger-downstream: variables: ENVIRONMENT: something trigger: my/project @@ -156,14 +157,14 @@ example, predefined variables. In order to do that, you can use interpolation to pass any variable. For example: ```yaml -my-pipeline: +downstream-job: variables: UPSTREAM_BRANCH: $CI_COMMIT_REF_NAME trigger: my/project ``` In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the -upstream pipeline will be passed to a `downstream` job, and will be available +upstream pipeline will be passed to the `downstream-job` job, and will be available within the context of all downstream builds. ### Demos diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 2157a6dc097..c851931e85c 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -1,5 +1,6 @@ --- table_display_block: true +type: reference --- # GitLab CI/CD environment variables @@ -86,7 +87,7 @@ Variable types can be set via the [UI](#via-the-ui) or the [API](../../api/proje > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/13784) in GitLab 11.10 -By default, variables will be created as masked variables. +Variables can be created as masked variables. This means that the value of the variable will be hidden in job logs, though it must match certain requirements to do so: @@ -388,21 +389,9 @@ Once you set them, they will be available for all subsequent pipelines. ### Limiting environment scopes of environment variables **[PREMIUM]** -> [Introduced][ee-2112] in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. - You can limit the environment scope of a variable by [defining which environments][envs] it can be available for. -Wildcards can be used, and the default environment scope is `*` which means -any jobs will have this variable, not matter if an environment is defined or -not. - -For example, if the environment scope is `production`, then only the jobs -having the environment `production` defined would have this specific variable. -Wildcards (`*`) can be used along with the environment name, therefore if the -environment scope is `review/*` then any jobs with environment names starting -with `review/` would have that particular variable. - To learn more about about scoping environments, see [Scoping environments with specs](../environments.md#scoping-environments-with-specs-premium). ### Deployment environment variables @@ -716,7 +705,6 @@ MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw' ... ``` -[ee-2112]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112 [ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI variables" [envs]: ../environments.md [protected branches]: ../../user/project/protected_branches.md diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md index 2642c9b0eb4..cdca5bf27fc 100644 --- a/doc/ci/variables/deprecated_variables.md +++ b/doc/ci/variables/deprecated_variables.md @@ -1,5 +1,12 @@ +--- +type: reference +--- + # Deprecated GitLab CI/CD variables +Read through this document to learn what predefined variables +were deprecated and their new references. + ## GitLab 9.0 renamed variables To follow conventions of naming across GitLab, and to further move away from the diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 4e902c042e6..4655eec51de 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Predefined environment variables reference For an introduction on this subject, read through the diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 0470cf52654..8009b1d5e8a 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Where variables can be used As it's described in the [CI/CD variables](README.md) docs, you can diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 18c85618b1b..716363a8d6d 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # GitLab CI/CD Pipeline Configuration Reference GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project. @@ -108,7 +112,7 @@ The following table lists available parameters for jobs: | [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`trigger`](#trigger-premium) | Defines a downstream pipeline trigger. | | [`include`](#include) | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. | -| [`extends`](#extends) | Configuration entry that this job is going to inherit from. | +| [`extends`](#extends) | Configuration entries that this job is going to inherit from. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`variables`](#variables) | Define job variables on a job level. | @@ -2117,7 +2121,7 @@ docker-test: > Introduced in GitLab 11.3. -`extends` defines an entry name that a job that uses `extends` is going to +`extends` defines entry names that a job that uses `extends` is going to inherit from. It is an alternative to using [YAML anchors](#anchors) and is a little @@ -2194,6 +2198,46 @@ spinach: script: rake spinach ``` +It's also possible to use multiple parents for `extends`. +The algorithm used for merge is "closest scope wins", so keys +from the last member will always shadow anything defined on other levels. +For example: + +```yaml +.only-important: + only: + - master + - stable + tags: + - production + +.in-docker: + tags: + - docker + image: alpine + +rspec: + extends: + - .only-important + - .in-docker + script: + - rake rspec +``` + +This results in the following `rspec` job: + +```yaml +rspec: + only: + - master + - stable + tags: + - docker + image: alpine + script: + - rake rspec +``` + ### Using `extends` and `include` together `extends` works across configuration files combined with `include`. @@ -2747,6 +2791,18 @@ using Git 2.10 or newer: git push -o ci.skip ``` +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> + [ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323 [ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669 [ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983 |