From a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Wed, 16 Jun 2021 18:25:58 +0000 Subject: Add latest changes from gitlab-org/gitlab@14-0-stable-ee --- doc/ci/README.md | 4 +- doc/ci/caching/index.md | 114 +-- doc/ci/chatops/README.md | 1 + .../bitbucket_integration.md | 2 +- .../ci_cd_for_external_repos/github_integration.md | 2 +- doc/ci/ci_cd_for_external_repos/index.md | 2 +- doc/ci/directed_acyclic_graph/index.md | 2 +- doc/ci/docker/README.md | 1 + doc/ci/docker/index.md | 2 +- doc/ci/docker/using_docker_build.md | 9 +- doc/ci/docker/using_docker_images.md | 4 + doc/ci/docker/using_kaniko.md | 8 +- doc/ci/enable_or_disable_ci.md | 2 +- doc/ci/environments/deployment_safety.md | 4 +- doc/ci/environments/environments_dashboard.md | 4 +- doc/ci/environments/index.md | 32 +- doc/ci/environments/protected_environments.md | 136 ++- doc/ci/examples/README.md | 6 +- .../authenticating-with-hashicorp-vault/index.md | 5 + .../laravel_with_gitlab_and_envoy/index.md | 22 +- doc/ci/examples/php.md | 2 +- ...test-and-deploy-python-application-to-heroku.md | 1 + .../test-and-deploy-ruby-application-to-heroku.md | 1 + doc/ci/examples/test-clojure-application.md | 1 + doc/ci/git_submodules.md | 4 +- doc/ci/interactive_web_terminal/index.md | 2 +- doc/ci/introduction/index.md | 2 +- doc/ci/jobs/index.md | 6 +- doc/ci/jobs/job_control.md | 391 +++++++- doc/ci/large_repositories/index.md | 16 +- doc/ci/merge_request_pipelines/index.md | 18 +- .../pipelines_for_merged_results/index.md | 4 +- .../merge_trains/index.md | 7 +- doc/ci/migration/circleci.md | 14 +- doc/ci/migration/jenkins.md | 20 +- doc/ci/multi_project_pipelines.md | 2 +- doc/ci/parent_child_pipelines.md | 4 +- doc/ci/pipelines/index.md | 13 +- doc/ci/pipelines/job_artifacts.md | 12 +- doc/ci/pipelines/pipeline_architectures.md | 4 +- doc/ci/pipelines/pipeline_artifacts.md | 13 +- doc/ci/pipelines/pipeline_efficiency.md | 4 +- doc/ci/pipelines/schedules.md | 23 +- doc/ci/pipelines/settings.md | 26 +- doc/ci/quick_start/README.md | 1 + doc/ci/quick_start/index.md | 18 +- doc/ci/review_apps/index.md | 2 +- doc/ci/runners/README.md | 1037 +++++--------------- doc/ci/runners/configure_runners.md | 601 ++++++++++++ doc/ci/runners/runners_scope.md | 251 +++++ doc/ci/services/README.md | 1 + doc/ci/services/gitlab.md | 2 +- doc/ci/ssh_keys/README.md | 1 + doc/ci/ssh_keys/index.md | 2 +- doc/ci/triggers/README.md | 38 +- doc/ci/troubleshooting.md | 8 +- doc/ci/unit_test_reports.md | 23 +- doc/ci/variables/README.md | 258 +---- doc/ci/variables/predefined_variables.md | 6 +- doc/ci/variables/where_variables_can_be_used.md | 11 +- doc/ci/yaml/README.md | 623 +++--------- doc/ci/yaml/gitlab_ci_yaml.md | 2 +- doc/ci/yaml/includes.md | 22 +- doc/ci/yaml/script.md | 2 +- 64 files changed, 2085 insertions(+), 1776 deletions(-) create mode 100644 doc/ci/runners/configure_runners.md create mode 100644 doc/ci/runners/runners_scope.md (limited to 'doc/ci') diff --git a/doc/ci/README.md b/doc/ci/README.md index 30a6668dbfd..dc4312250ca 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 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." @@ -70,7 +70,7 @@ GitLab CI/CD supports numerous configuration options: | Configuration | Description | |:----------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------| | [Schedule pipelines](pipelines/schedules.md) | Schedule pipelines to run as often as you need. | -| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-cicd-configuration-path) | Define a custom path for the CI/CD configuration file. | +| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-cicd-configuration-file) | Define a custom path for the CI/CD configuration file. | | [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules. | | [SSH keys for CI/CD](ssh_keys/index.md) | Using SSH keys in your CI pipelines. | | [Pipeline triggers](triggers/README.md) | Trigger pipelines through the API. | diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index f2cb9500b2c..0778d598d32 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,77 +1,39 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- -# Cache dependencies in GitLab CI/CD +# Caching in GitLab CI/CD -GitLab CI/CD provides a caching mechanism that can be used to save time -when your jobs are running. +A cache is one or more files that a job downloads and saves. Subsequent jobs that use +the same cache don't have to download the files again, so they execute more quickly. -Caching is about speeding the time a job is executed by reusing the same -content of a previous job. Use caching when you are -developing software that depends on other libraries which are fetched via the -internet during build time. +To learn how to define the cache in your `.gitlab-ci.yml` file, +see the [`cache` reference](../yaml/README.md#cache). -If caching is enabled, it's shared between pipelines and jobs at the project -level by default. Caches are not shared across projects. +## How cache is different from artifacts -Make sure you read the [`cache` reference](../yaml/README.md#cache) to learn -how it is defined in `.gitlab-ci.yml`. +Use cache for dependencies, like packages you download from the internet. +Cache is stored where GitLab Runner is installed and uploaded to S3 if +[distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). -## Cache vs artifacts +- You can define it per job by using the `cache:` keyword. Otherwise it is disabled. +- You can define it per job so that: + - Subsequent pipelines can use it. + - Subsequent jobs in the same pipeline can use it, if the dependencies are identical. +- You cannot share it between projects. -If you use cache and artifacts to store the same path in your jobs, the cache might -be overwritten because caches are restored before artifacts. - -Don't use caching for passing artifacts between stages, as it is designed to store -runtime dependencies needed to compile the project: - -- `cache`: **For storing project dependencies** - - Caches can increase the speed of a given job in subsequent pipelines. You can - store downloaded dependencies so that they don't have to be fetched from the - internet again. Dependencies include things like npm packages, Go vendor packages, and so on. - You can configure a cache to pass intermediate build results between stages, - but you should use artifacts instead. - -- `artifacts`: **Use for stage results that are passed between stages.** - - Artifacts are files that are generated by a job so they can be stored and uploaded. You can - fetch and use artifacts in jobs in later stages of the same pipeline. You can't - create an artifact in a job in one stage, and use this artifact in a different job in - the same stage. This data is not available in different pipelines, but can be downloaded - from the UI. - - If you download modules while building your application, you can declare them as - artifacts and subsequent stage jobs can use them. +Use artifacts to pass intermediate build results between stages. +Artifacts are generated by a job, stored in GitLab, and can be downloaded. - You can define an [expiry time](../yaml/README.md#artifactsexpire_in) so artifacts - are deleted after a defined time. Use [dependencies](../yaml/README.md#dependencies) - to control which jobs fetch the artifacts. +- You can define artifacts per job. Subsequent jobs in later stages of the same + pipeline can use them. +- You can't use the artifacts in a different pipeline. - Artifacts can also be used to make files available for download after a pipeline - completes, like a build image. - -Caches: - -- Are disabled if not defined globally or per job (using `cache:`). -- Are available for all jobs in your `.gitlab-ci.yml` if enabled globally. -- Can be used in subsequent pipelines by the same job in which the cache was created (if not defined globally). -- Are stored where GitLab Runner is installed **and** uploaded to S3 if [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). -- If defined per job, are used: - - By the same job in a subsequent pipeline. - - By subsequent jobs in the same pipeline, if they have identical dependencies. - -Artifacts: - -- Are disabled if not defined per job (using `artifacts:`). -- Can only be enabled per job, not globally. -- Are created during a pipeline and can be used by subsequent jobs in the same pipeline. -- Are always uploaded to GitLab (known as coordinator). -- Can have an expiration value for controlling disk usage (30 days by default). +Artifacts expire after 30 days unless you define an [expiration time](../yaml/README.md#artifactsexpire_in). +Use [dependencies](../yaml/README.md#dependencies) to control which jobs fetch the artifacts. Both artifacts and caches define their paths relative to the project directory, and can't link to files outside it. @@ -81,10 +43,9 @@ can't link to files outside it. To ensure maximum availability of the cache, when you declare `cache` in your jobs, use one or more of the following: -- [Tag your runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs +- [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs that share their cache. -- [Use sticky runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - that are only available to a particular project. +- [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects). - [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the [predefined CI/CD variables](../variables/README.md#predefined-cicd-variables). @@ -102,7 +63,7 @@ For runners to work with caches efficiently, you must do one of the following: Read about the [availability of the cache](#availability-of-the-cache) to learn more about the internals and get a better idea how cache works. -### Share caches across the same branch +### Share caches between jobs in the same branch Define a cache with the `key: ${CI_COMMIT_REF_SLUG}` so that jobs of each branch always use the same cache: @@ -130,7 +91,7 @@ cache: key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG" ``` -### Share caches across different branches +### Share caches across jobs in different branches To share a cache across all branches and all jobs, use the same key for everything: @@ -146,7 +107,7 @@ cache: key: ${CI_JOB_NAME} ``` -### Disable cache on specific jobs +### Disable cache for specific jobs If you have defined the cache globally, it means that each job uses the same definition. You can override this behavior per-job, and if you want to @@ -189,7 +150,7 @@ The most common use case of caching is to avoid downloading content like depende or libraries repeatedly between subsequent runs of jobs. Node.js packages, PHP packages, Ruby gems, Python libraries, and others can all be cached. -For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). +For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). ### Cache Node.js dependencies @@ -201,7 +162,7 @@ Instead, we tell npm to use `./.npm`, and cache it per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates/Nodejs.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Nodejs.gitlab-ci.yml # image: node:latest @@ -219,7 +180,7 @@ test_async: - node ./specs/start.js ./specs/async.spec.js ``` -### Caching PHP dependencies +### Cache PHP dependencies Assuming your project is using [Composer](https://getcomposer.org/) to install the PHP dependencies, the following example defines `cache` globally so that @@ -228,7 +189,7 @@ are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates/PHP.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/PHP.gitlab-ci.yml # image: php:7.2 @@ -248,7 +209,7 @@ test: - vendor/bin/phpunit --configuration phpunit.xml --coverage-text --colors=never ``` -### Caching Python dependencies +### Cache Python dependencies Assuming your project is using [pip](https://pip.pypa.io/en/stable/) to install the Python dependencies, the following example defines `cache` globally so that @@ -257,7 +218,7 @@ pip's cache is defined under `.cache/pip/` and both are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml # image: python:latest @@ -289,7 +250,7 @@ test: - flake8 . ``` -### Caching Ruby dependencies +### Cache Ruby dependencies Assuming your project is using [Bundler](https://bundler.io) to install the gem dependencies, the following example defines `cache` globally so that all @@ -297,7 +258,7 @@ jobs inherit it. Gems are installed in `vendor/ruby/` and are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates/Ruby.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Ruby.gitlab-ci.yml # image: ruby:2.6 @@ -347,7 +308,7 @@ deploy_job: - bundle exec deploy ``` -### Caching Go dependencies +### Cache Go dependencies Assuming your project is using [Go Modules](https://github.com/golang/go/wiki/Modules) to install Go dependencies, the following example defines `cache` in a `go-cache` template, that @@ -396,6 +357,9 @@ machine where the runner is installed and depends on the type of the executor. | [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, stored under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#the-builds-and-cache-storage): `/var/lib/docker/volumes//_data////cache.zip`. | | [Docker machine](https://docs.gitlab.com/runner/executors/docker_machine.html) (autoscale runners) | Behaves the same as the Docker executor. | +If you use cache and artifacts to store the same path in your jobs, the cache might +be overwritten because caches are restored before artifacts. + ### How archiving and extracting works This example has two jobs that belong to two consecutive stages: diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index c94d6e3ea80..577a80407d7 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -1,5 +1,6 @@ --- redirect_to: 'index.md' +remove_date: '2021-05-01' --- This document was moved to [another location](index.md). diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index 38930eb60ad..4d3f12dff05 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index deadc4458a2..c6fa049dc6e 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index cc6c629fb47..8c961ea6128 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, howto --- diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index dab9d8b78ae..e9725a29fc7 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md index c94d6e3ea80..577a80407d7 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -1,5 +1,6 @@ --- redirect_to: 'index.md' +remove_date: '2021-05-01' --- This document was moved to [another location](index.md). diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 0897bb183e5..20599c5ca85 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 90a33478239..9dac08324c8 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -25,9 +25,8 @@ To enable Docker commands for your CI/CD jobs, you can use: If you don't want to execute a runner in privileged mode, but want to use `docker build`, you can also [use kaniko](using_kaniko.md). -If you are using shared runners on GitLab.com, see -[GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) -to learn more about how these runners are configured. +If you are using shared runners on GitLab.com, +[learn more about how these runners are configured](../runners/README.md). ### Use the shell executor @@ -91,7 +90,7 @@ The Docker image has all of the `docker` tools installed and can run the job script in context of the image in privileged mode. We recommend you use [Docker-in-Docker with TLS enabled](#docker-in-docker-with-tls-enabled), -which is supported by [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners). +which is supported by [GitLab.com shared runners](../runners/README.md). You should always specify a specific version of the image, like `docker:19.03.12`. If you use a tag like `docker:stable`, you have no control over which version is used. diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 173701ef358..29f4053f720 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -128,6 +128,10 @@ For example, the following two definitions are equal: - name: redis:latest ``` +## Where scripts are executed + +When a CI job runs in a Docker container, the `before_script`, `script`, and `after_script` commands run in the `/builds//` directory. Your image may have a different default `WORKDIR` defined. To move to your `WORKDIR`, save the `WORKDIR` as an environment variable so you can reference it in the container during the job's runtime. + ### Available settings for `image` > Introduced in GitLab and GitLab Runner 9.4. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 0344e736dd4..05769cc8f75 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -99,8 +99,8 @@ build: KANIKOCFG="${KANIKOCFG} }" echo "${KANIKOCFG}" > /kaniko/.docker/config.json - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile $KANIKOPROXYBUILDARGS --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG - only: - - tags + rules: + - if: $CI_COMMIT_TAG ``` ## Using a registry with a custom certificate @@ -133,7 +133,7 @@ The [Least Privilege Container Builds with Kaniko on GitLab](https://www.youtube video is a walkthrough of the [Kaniko Docker Build](https://gitlab.com/guided-explorations/containers/kaniko-docker-build) Guided Exploration project pipeline. It was tested on: -- [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) +- [GitLab.com shared runners](../runners/README.md) - [The Kubernetes runner executor](https://docs.gitlab.com/runner/executors/kubernetes.html) The example can be copied to your own group or instance for testing. More details diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 72fd9833df1..4633cc1a3f8 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 6fda6bb0d8b..c57dc99f341 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -117,7 +117,7 @@ The other pipelines don't get the protected variable. You can also [scope variables to specific environments](../variables/where_variables_can_be_used.md#variables-with-an-environment-scope). We recommend that you use protected variables on protected environments to make sure that the secrets aren't exposed unintentionally. You can also define production secrets on the -[runner side](../runners/README.md#prevent-runners-from-revealing-sensitive-information). +[runner side](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). This prevents other maintainers from reading the secrets and makes sure that the runner only runs on protected branches. @@ -141,7 +141,7 @@ reference a file in another project with a completely different set of permissio In this scenario, the `gitlab-ci.yml` is publicly accessible, but can only be edited by users with appropriate permissions in the other project. -For more information, see [Custom CI/CD configuration path](../pipelines/settings.md#custom-cicd-configuration-path). +For more information, see [Custom CI/CD configuration path](../pipelines/settings.md#custom-cicd-configuration-file). ## Troubleshooting diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 4ee9aa9a5ba..a89bc1c89aa 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -20,8 +20,8 @@ see which pipelines are green and which are red allowing you to diagnose if there is a block at a particular point, or if there's a more systemic problem you need to investigate. -You can access the dashboard from the top bar by clicking -**More > Environments**. +You can access the dashboard on the top bar by selecting +**Menu > Environments**. ![Environments Dashboard with projects](img/environments_dashboard_v12_5.png) diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 06618a820db..62c58302886 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -31,7 +31,7 @@ Prerequisites: To view a list of environments and deployments: -1. Go to the project's **Operations > Environments** page. +1. Go to the project's **Deployments > Environments** page. The environments are displayed. ![Environments list](img/environments_list.png) @@ -57,7 +57,7 @@ You can create an environment and deployment in the UI or in your `.gitlab-ci.ym In the UI: -1. Go to the project's **Operations > Environments** page. +1. Go to the project's **Deployments > Environments** page. 1. Select **New environment**. 1. Enter a name and external URL. 1. Select **Save**. @@ -99,10 +99,10 @@ deploy_review: environment: name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com - only: - - branches - except: - - master + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + when: never + - if: $CI_COMMIT_BRANCH ``` In this example: @@ -136,7 +136,7 @@ you can use tiers: | Environment tier | Environment name examples | |------------------|----------------------------------------------------| | `production` | Production, Live | -| `staging` | Staging, Model, Pre, Demo | +| `staging` | Staging, Model, Demo | | `testing` | Test, QC | | `development` | Dev, [Review apps](../review_apps/index.md), Trunk | | `other` | | @@ -158,8 +158,8 @@ deploy_prod: name: production url: https://example.com when: manual - only: - - master + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` The `when: manual` action: @@ -200,8 +200,8 @@ deploy: url: https://example.com kubernetes: namespace: production - only: - - master + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster, @@ -326,7 +326,7 @@ If there is a problem with a deployment, you can retry it or roll it back. To retry or rollback a deployment: -1. Go to the project's **Operations > Environments**. +1. Go to the project's **Deployments > Environments**. 1. Select the environment. 1. To the right of the deployment name: - To retry a deployment, select **Re-deploy to environment**. @@ -409,7 +409,7 @@ The job with [`action: stop` might not run](#the-job-with-action-stop-doesnt-run if it's in a later stage than the job that started the environment. If you can't use [pipelines for merge requests](../merge_request_pipelines/index.md), -set the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` in the +set the [`GIT_STRATEGY`](../runners/configure_runners.md#git-strategy) to `none` in the `stop_review` job. Then the [runner](https://docs.gitlab.com/runner/) doesn't try to check out the code after the branch is deleted. @@ -465,7 +465,7 @@ GitLab automatically triggers the `stop_review_app` job to stop the environment. You can view a deployment's expiration date in the GitLab UI. -1. Go to the project's **Operations > Environments** page. +1. Go to the project's **Deployments > Environments** page. 1. Select the name of the deployment. In the top left, next to the environment name, the expiration date is displayed. @@ -474,7 +474,7 @@ In the top left, next to the environment name, the expiration date is displayed. You can manually override a deployment's expiration date. -1. Go to the project's **Operations > Environments** page. +1. Go to the project's **Deployments > Environments** page. 1. Select the deployment name. 1. On the top right, select the thumbtack (**{thumbtack}**). @@ -491,7 +491,7 @@ You can delete [stopped environments](#stopping-an-environment) in the GitLab UI To delete a stopped environment in the GitLab UI: -1. Go to the project's **Operations > Environments** page. +1. Go to the project's **Deployments > Environments** page. 1. Select the **Stopped** tab. 1. Next to the environment you want to delete, select **Delete environment**. 1. On the confirmation dialog box, select **Delete environment**. diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index df0bb2817ab..c276059cb9e 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -23,8 +23,8 @@ with the right privileges can deploy to it, thus keeping it safe. NOTE: A GitLab admin is always allowed to use environments, even if they are protected. -To protect, update, or unprotect an environment, you need to have at least -[Maintainer permissions](../../user/permissions.md). +To protect, update, or unprotect an environment, you need to have at least the +[Maintainer role](../../user/permissions.md). ## Protecting environments @@ -79,7 +79,8 @@ Alternatively, you can use the API to protect an environment: 1. Use the API to add a user to the group as a reporter: ```shell - $ curl --request POST --header "PRIVATE-TOKEN: " --data "user_id=3222377&access_level=20" "https://gitlab.com/api/v4/groups/9899826/members" + $ curl --request POST --header "PRIVATE-TOKEN: " \ + --data "user_id=3222377&access_level=20" "https://gitlab.com/api/v4/groups/9899826/members" {"id":3222377,"name":"Sean Carroll","username":"sfcarroll","state":"active","avatar_url":"https://assets.gitlab-static.net/uploads/-/system/user/avatar/3222377/avatar.png","web_url":"https://gitlab.com/sfcarroll","access_level":20,"created_at":"2020-10-26T17:37:50.309Z","expires_at":null} ``` @@ -87,7 +88,8 @@ Alternatively, you can use the API to protect an environment: 1. Use the API to add the group to the project as a reporter: ```shell - $ curl --request POST --header "PRIVATE-TOKEN: " --request POST "https://gitlab.com/api/v4/projects/22034114/share?group_id=9899826&group_access=20" + $ curl --request POST --header "PRIVATE-TOKEN: " \ + --request POST "https://gitlab.com/api/v4/projects/22034114/share?group_id=9899826&group_access=20" {"id":1233335,"project_id":22034114,"group_id":9899826,"group_access":20,"expires_at":null} ``` @@ -95,7 +97,8 @@ Alternatively, you can use the API to protect an environment: 1. Use the API to add the group with protected environment access: ```shell - curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: " "https://gitlab.com/api/v4/projects/22034114/protected_environments" + curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' \ + --header "PRIVATE-TOKEN: " "https://gitlab.com/api/v4/projects/22034114/protected_environments" ``` The group now has access and can be seen in the UI. @@ -151,6 +154,129 @@ be re-entered if the environment is re-protected. For more information, see [Deployment safety](deployment_safety.md). +## Group-level protected environments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-level-protected-environments). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +Typically, large enterprise organizations have an explicit permission boundary +between [developers and operators](https://about.gitlab.com/topics/devops/). +Developers build and test their code, and operators deploy and monitor the +application. With group-level protected environments, the permission of each +group is carefully configured in order to prevent unauthorized access and +maintain proper separation of duty. Group-level protected environments +extend the [project-level protected environments](#protecting-environments) +to the group-level. + +The permissions of deployments can be illustrated in the following table: + +| Environment | Developer | Operator | Category | +|-------------|------------|----------|----------| +| Development | Allowed | Allowed | Lower environment | +| Testing | Allowed | Allowed | Lower environment | +| Staging | Disallowed | Allowed | Higher environment | +| Production | Disallowed | Allowed | Higher environment | + +_(Reference: [Deployment environments on Wikipedia](https://en.wikipedia.org/wiki/Deployment_environment))_ + +### Group-level protected environments names + +Contrary to project-level protected environments, group-level protected +environments use the [deployment tier](index.md#deployment-tier-of-environments) +as their name. + +A group may consist of many project environments that have unique names. +For example, Project-A has a `gprd` environment and Project-B has a `Production` +environment, so protecting a specific environment name doesn't scale well. +By using deployment tiers, both are recognized as `production` deployment tier +and are protected at the same time. + +### Configure group-level memberships + +In an enterprise organization, with thousands of projects under a single group, +ensuring that all of the [project-level protected environments](#protecting-environments) +are properly configured is not a scalable solution. For example, a developer +might gain privileged access to a higher environment when they are added as a +maintainer to a new project. Group-level protected environments can be a solution +in this situation. + +To maximize the effectiveness of group-level protected environments, +[group-level memberships](../../user/group/index.md) must be correctly +configured: + +- Operators should be assigned the [maintainer role](../../user/permissions.md) + (or above) to the top-level group. They can maintain CI/CD configurations for + the higher environments (such as production) in the group-level settings page, + wnich includes group-level protected environments, + [group-level runners](../runners/runners_scope.md#group-runners), + [group-level clusters](../../user/group/clusters/index.md), etc. Those + configurations are inherited to the child projects as read-only entries. + This ensures that only operators can configure the organization-wide + deployment ruleset. +- Developers should be assigned the [developer role](../../user/permissions.md) + (or below) at the top-level group, or explicitly assigned to a child project + as maintainers. They do *NOT* have access to the CI/CD configurations in the + top-level group, so operators can ensure that the critical configuration won't + be accidentally changed by the developers. +- For sub-groups and child projects: + - Regarding [sub-groups](../../user/group/subgroups/index.md), if a higher + group has configured the group-level protected environment, the lower groups + cannot override it. + - [Project-level protected environments](#protecting-environments) can be + combined with the group-level setting. If both group-level and project-level + environment configurations exist, the user must be allowed in **both** + rulesets in order to run a deployment job. + - Within a project or a sub-group of the top-level group, developers can be + safely assigned the Maintainer role to tune their lower environments (such + as `testing`). + +Having this configuration in place: + +- If a user is about to run a deployment job in a project and allowed to deploy + to the environment, the deployment job proceeds. +- If a user is about to run a deployment job in a project but disallowed to + deploy to the environment, the deployment job fails with an error message. + +### Protect a group-level environment + +To protect a group-level environment: + +1. Make sure your environments have the correct + [`deployment_tier`](index.md#deployment-tier-of-environments) defined in + `gitlab-ci.yml`. +1. Configure the group-level protected environments via the + [REST API](../../api/group_protected_environments.md). + +NOTE: +Configuration [via the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/325249) +is scheduled for a later release. + +### Enable or disable Group-level protected environments **(FREE SELF)** + +Group-level protected environments is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:group_level_protected_environments) +``` + +To disable it: + +```ruby +Feature.disable(:group_level_protected_environments) +``` + @@ -318,7 +318,7 @@ Markdown code embeds the test coverage report badge of the `coverage` job into your `README.md`: ```markdown -![coverage](https://gitlab.com/gitlab-org/gitlab/badges/master/coverage.svg?job=coverage) +![coverage](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=coverage) ``` ### Badge styles @@ -331,7 +331,7 @@ Pipeline badges can be rendered in different styles by adding the `style=style_n https://gitlab.example.com///badges//coverage.svg?style=flat ``` - ![Badge flat style](https://gitlab.com/gitlab-org/gitlab/badges/master/coverage.svg?job=coverage&style=flat) + ![Badge flat style](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=coverage&style=flat) - Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): @@ -339,7 +339,7 @@ Pipeline badges can be rendered in different styles by adding the `style=style_n https://gitlab.example.com///badges//coverage.svg?style=flat-square ``` - ![Badge flat square style](https://gitlab.com/gitlab-org/gitlab/badges/master/coverage.svg?job=coverage&style=flat-square) + ![Badge flat square style](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=coverage&style=flat-square) ### Custom badge text @@ -348,10 +348,10 @@ Pipeline badges can be rendered in different styles by adding the `style=style_n The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: ```plaintext -https://gitlab.com/gitlab-org/gitlab/badges/master/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 +https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 ``` -![Badge with custom text and width](https://gitlab.com/gitlab-org/gitlab/badges/master/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130) +![Badge with custom text and width](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130)