diff options
Diffstat (limited to 'doc/ci')
61 files changed, 844 insertions, 633 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 87c7af2030d..29a03fe06ab 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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: index, concepts, howto --- @@ -37,15 +37,15 @@ can't link to files outside it. - Define artifacts per job. - Subsequent jobs in later stages of the same pipeline can use artifacts. - Different projects cannot share artifacts. - -Artifacts expire after 30 days unless you define an [expiration time](../yaml/index.md#artifactsexpire_in). -Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts. +- Artifacts expire after 30 days by default. You can define a custom [expiration time](../yaml/index.md#artifactsexpire_in). +- The latest artifacts do not expire if [keep latest artifacts](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) is enabled. +- Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts. ## Good caching practices To ensure maximum availability of the cache, do one or more of the following: -- [Tag your runners](../runners/configure_runners.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-control-which-jobs-a-runner-can-run) and use the tag on jobs that share the cache. - [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/index.md#cachekey) that fits your workflow. For example, diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index a461147661c..a2d9cf9054d 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -7,8 +7,8 @@ type: index, concepts, howto # GitLab ChatOps **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in GitLab Ultimate 10.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting takes 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 60a939496d6..70a9c8fc775 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -29,7 +29,7 @@ repositories: 1. In GitHub, create a token: 1. Open <https://github.com/settings/tokens/new>. - 1. Create a **Personal Access Token**. + 1. Create a **Personal Access Token**. 1. Enter a **Token description** and update the scope to allow `repo` and `admin:repo_hook` so that GitLab can access your project, update commit statuses, and create a web hook to notify GitLab of new commits. @@ -57,7 +57,7 @@ To manually enable GitLab CI/CD for your repository: 1. In GitHub, create a token: 1. Open <https://github.com/settings/tokens/new>. - 1. Create a **Personal Access Token**. + 1. Create a **Personal Access Token**. 1. Enter a **Token description** and update the scope to allow `repo` so that GitLab can access your project and update commit statuses. 1. In GitLab, create a project: diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 27c808791e5..365e2ee31de 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -7,7 +7,7 @@ type: index, howto # GitLab CI/CD for external repositories **(PREMIUM)** ->[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. +>[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in GitLab 10.6. GitLab CI/CD can be used with: @@ -38,7 +38,7 @@ To connect to an external repository: ## Pipelines for external pull requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65139) in GitLab Premium 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65139) in GitLab 12.3. When using GitLab CI/CD with an [external repository on GitHub](github_integration.md), it's possible to run a pipeline in the context of a Pull Request. diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index a4b4fd9fd16..25b87366a30 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -95,7 +95,7 @@ GitLab provides a series of [CI templates that you can include in your project]( To automate deployments of your application to your [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (AWS ECS) cluster, you can `include` the `AWS/Deploy-ECS.gitlab-ci.yml` template in your `.gitlab-ci.yml` file. -GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `gitlab-ci.yml` file to simplify working with AWS: +GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `.gitlab-ci.yml` file to simplify working with AWS: - Use `registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest` to use AWS CLI commands. - Use `registry.gitlab.com/gitlab-org/cloud-deploy/aws-ecs:latest` to deploy your application to AWS ECS. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index d965d4b83f9..11ba1e40b3e 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Directed Acyclic Graph +# Directed Acyclic Graph **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/206902) in GitLab 12.10. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index c56bc9a4dc8..d5adedc611c 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -23,7 +23,7 @@ To enable Docker commands for your CI/CD jobs, you can use: - [Docker socket binding](#use-docker-socket-binding) 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). +but want to use `docker build`, you can also use [`kaniko`](using_kaniko.md) or [`buildah`](https://github.com/containers/buildah). If you are using shared runners on GitLab.com, [learn more about how these runners are configured](../runners/index.md). diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 421bca9e324..65c907b8e7b 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -7,34 +7,33 @@ type: howto # How to enable or disable GitLab CI/CD **(FREE)** -To effectively use GitLab CI/CD, you need: +To use GitLab CI/CD, you need: - A valid [`.gitlab-ci.yml`](yaml/index.md) file present at the root directory of your project. -- A [runner](runners/index.md) properly set up. +- A [runner](runners/index.md) ready to run jobs. You can read our [quick start guide](quick_start/index.md) to get you started. -If you are using an external CI/CD server like Jenkins or Drone CI, it is advised -to disable GitLab CI/CD in order to not have any conflicts with the commits status +If you use an external CI/CD server like Jenkins or Drone CI, you can +disable GitLab CI/CD to avoid conflicts with the commits status API. -GitLab CI/CD is exposed by using the `/pipelines` and `/jobs` pages of a project. -Disabling GitLab CI/CD in a project does not delete any previous jobs. -In fact, the `/pipelines` and `/jobs` pages can still be accessed, although -it's hidden from the left sidebar menu. +GitLab CI/CD is enabled by default on all new projects. You can: -GitLab CI/CD is enabled by default on new installations and can be disabled -either: +- Disable GitLab CI/CD [under each project's settings](#enable-cicd-in-a-project). +- Set GitLab CI/CD to be [disabled in all new projects on an instance](../administration/cicd.md). -- Individually under each project's settings. -- Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source - and Omnibus installations respectively. +If you disable GitLab CI/CD in a project: -This only applies to pipelines run as part of GitLab CI/CD. This doesn't enable or disable -pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing). +- The **CI/CD** item in the left sidebar is removed. +- The `/pipelines` and `/jobs` pages are no longer available. +- Existing jobs and pipelines are not deleted. Re-enable CI/CD to access them again. -## Per-project user setting +The project or instance settings do not enable or disable pipelines run in an +[external integration](../user/project/integrations/overview.md#integrations-listing). + +## Enable CI/CD in a project To enable or disable GitLab CI/CD pipelines in your project: @@ -51,54 +50,6 @@ To enable or disable GitLab CI/CD pipelines in your project: Press **Save changes** for the settings to take effect. -## Make GitLab CI/CD disabled by default in new projects - -You can set GitLab CI/CD to be disabled by default in all new projects by modifying the settings in: - -- `gitlab.yml` for source installations. -- `gitlab.rb` for Omnibus GitLab installations. - -Existing projects that already had CI/CD enabled are unchanged. Also, this setting only changes -the project default, so project owners can still enable CI/CD in the project settings. - -For installations from source: - -1. Open `gitlab.yml` with your editor and set `builds` to `false`: - - ```yaml - ## Default project features settings - default_projects_features: - issues: true - merge_requests: true - wiki: true - snippets: false - builds: false - ``` - -1. Save the `gitlab.yml` file. - -1. Restart GitLab: - - ```shell - sudo service gitlab restart - ``` - -For Omnibus GitLab installations: - -1. Edit `/etc/gitlab/gitlab.rb` and add this line: - - ```ruby - gitlab_rails['gitlab_default_projects_features_builds'] = false - ``` - -1. Save the `/etc/gitlab/gitlab.rb` file. - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 4e34cc7ce38..1b34b520007 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -136,10 +136,10 @@ connect the CD project to your development projects by using [multi-project pipe A `.gitlab-ci.yml` may contain rules to deploy an application to the production server. This deployment usually runs automatically after pushing a merge request. To prevent developers from -changing the `gitlab-ci.yml`, you can define it in a different repository. The configuration can +changing the `.gitlab-ci.yml`, you can define it in a different repository. The configuration can reference a file in another project with a completely different set of permissions (similar to [separating a project for deployments](#separate-project-for-deployments)). -In this scenario, the `gitlab-ci.yml` is publicly accessible, but can only be edited by users with +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#specify-a-custom-cicd-configuration-file). diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index ae459b9016c..8ff31827ae7 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -7,7 +7,7 @@ type: reference # Environments Dashboard **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3713) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3713) in GitLab 12.5. The Environments Dashboard provides a cross-project environment-based view that lets you see the big picture diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index e473d52f957..bc52fd1f16c 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -43,7 +43,7 @@ number of pods that are defined for the deployment, which are configured when th cluster is created. For example, if your application has 10 pods and a 10% rollout job runs, the new instance of the -application is deployed to a single pod while the remaining nine are present the previous instance. +application is deployed to a single pod while the rest of the pods show the previous instance of the application. First we [define the template as manual](https://gitlab.com/gl-release/incremental-rollout-example/blob/master/.gitlab-ci.yml#L100-103): @@ -135,5 +135,5 @@ to switch to a different deployment. Both deployments are running in parallel, a can be switched to at any time. An [example deployable application](https://gitlab.com/gl-release/blue-green-example) -is available, with a [`gitlab-ci.yml` CI/CD configuration file](https://gitlab.com/gl-release/blue-green-example/blob/master/.gitlab-ci.yml) +is available, with a [`.gitlab-ci.yml` CI/CD configuration file](https://gitlab.com/gl-release/blue-green-example/blob/master/.gitlab-ci.yml) that demonstrates blue-green deployments. diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 1b4d8890c6e..6bac004fcdf 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -99,7 +99,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH @@ -109,9 +109,9 @@ deploy_review: In this example: -- The `name` is `review/$CI_COMMIT_REF_NAME`. Because the [environment name](../yaml/index.md#environmentname) +- The `name` is `review/$CI_COMMIT_REF_SLUG`. Because the [environment name](../yaml/index.md#environmentname) can contain slashes (`/`), you can use this pattern to distinguish between dynamic and static environments. -- For the `url`, you could use `$CI_COMMIT_REF_NAME`, but because this value +- For the `url`, you could use `$CI_COMMIT_REF_SLUG`, but because this value may contain a `/` or other characters that would not be valid in a domain name or URL, use `$CI_ENVIRONMENT_SLUG` instead. The `$CI_ENVIRONMENT_SLUG` variable is guaranteed to be unique. @@ -177,7 +177,7 @@ You can find the play button in the pipelines, environments, deployments, and jo If you are deploying to a [Kubernetes cluster](../../user/project/clusters/index.md) associated with your project, you can configure these deployments from your -`gitlab-ci.yml` file. +`.gitlab-ci.yml` file. NOTE: Kubernetes configuration isn't supported for Kubernetes clusters that are @@ -385,7 +385,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review rules: @@ -396,7 +396,7 @@ stop_review: script: - echo "Remove review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop rules: - if: $CI_MERGE_REQUEST_ID @@ -440,7 +440,7 @@ is created or updated. The environment runs until `stop_review_app` is executed: review_app: script: deploy-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG on_stop: stop_review_app auto_stop_in: 1 week rules: @@ -449,7 +449,7 @@ review_app: stop_review_app: script: stop-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop rules: - if: $CI_MERGE_REQUEST_ID @@ -538,7 +538,7 @@ then in the UI, the environments are grouped under that heading:  The following example shows how to start your environment names with `review`. -The `$CI_COMMIT_REF_NAME` variable is populated with the branch name at runtime: +The `$CI_COMMIT_REF_SLUG` variable is populated with the branch name at runtime: ```yaml deploy_review: @@ -546,7 +546,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG ``` ### Environment incident management @@ -566,7 +566,7 @@ to get alerts when there are critical issues that need immediate attention. #### View the latest alerts for environments **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in GitLab 13.4. If you [set up alerts for Prometheus metrics](../../operations/metrics/alerts.md), alerts for environments are shown on the environments page. The alert with the highest @@ -582,7 +582,7 @@ deployment tab from the environment page and select which deployment to roll bac #### Auto Rollback **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35404) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35404) in GitLab 13.7. In a typical Continuous Deployment workflow, the CI pipeline tests every commit before deploying to production. However, problematic code can still make it to production. For example, inefficient code @@ -682,9 +682,9 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scope environments with specs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. -> - [Environment scoping for CI/CD variables was moved to all tiers](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2. -> - [Environment scoping for Group CI/CD variables](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) added to GitLab Premium in 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in GitLab Premium 9.4. +> - Environment scoping for CI/CD variables was [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) from GitLab Premium to GitLab Free in 12.2. +> - Environment scoping for Group CI/CD variables [added](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) to GitLab Premium in 13.11. You can limit the environment scope of a CI/CD variable by defining which environments it can be available for. @@ -728,11 +728,24 @@ like [Review Apps](../review_apps/index.md) (`review/*`). The most specific spec takes precedence over the other wildcard matching. In this case, the `review/feature-1` spec takes precedence over `review/*` and `*` specs. +### Rename an environment + +> Renaming environments through the UI was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68550) in GitLab 14.3. Renaming environments through the API was deprecated and [will be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) in GitLab 15.0. + +Renaming an environment through the UI is not possible. +Instead, you need to delete the old environment and create a new one: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Deployments > Environments**. +1. Find the environment and stop it. +1. Delete the environment. +1. Create a new environment with your preferred name. + ## Related topics - [Use GitLab CI to deploy to multiple environments (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) - [Review Apps](../review_apps/index.md): Use dynamic environments to deploy your code for every branch. -- [Deploy Boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes. +- [Deploy boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes. - [Protected environments](protected_environments.md): Determine who can deploy code to your environments. - [Environments Dashboard](../environments/environments_dashboard.md): View a summary of each environment's operational health. **(PREMIUM)** @@ -763,14 +776,14 @@ To ensure the `action: stop` can always run when needed, you can: deploy_review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review stop_review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop when: manual ``` @@ -790,7 +803,7 @@ To ensure the `action: stop` can always run when needed, you can: deploy_review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review @@ -799,7 +812,7 @@ To ensure the `action: stop` can always run when needed, you can: needs: - deploy_review environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop when: manual ``` diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 3cd4ebdbdf1..b31e51b35fc 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -7,7 +7,7 @@ type: concepts, howto # Protected environments **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in GitLab 11.3. [Environments](../environments/index.md) can be used for different reasons: @@ -157,15 +157,9 @@ 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](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../../administration/feature_flags.md), disabled by default. +> - [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3. +> - [Generally Available](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) on GitLab and on GitLab.com in 14.3. Typically, large enterprise organizations have an explicit permission boundary between [developers and operators](https://about.gitlab.com/topics/devops/). @@ -251,7 +245,7 @@ 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`. + `.gitlab-ci.yml`. 1. Configure the group-level protected environments via the [REST API](../../api/group_protected_environments.md). @@ -259,25 +253,6 @@ 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) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 7a6d692cd43..06074d6edc2 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -11,7 +11,7 @@ description: 'Confidence checking your entire app every time a new feature is ad <!-- vale off --> -# End-to-end testing with GitLab CI/CD and WebdriverIO +# End-to-end testing with GitLab CI/CD and WebdriverIO **(FREE)** [Review Apps](../../review_apps/index.md) are great: for every merge request (or branch, for that matter), the new code can be copied and deployed to a fresh production-like live @@ -20,7 +20,7 @@ environment, reducing the effort to assess the impact of changes. Thus, when we and it will immediately be clear that the application can still be properly built and deployed. After all, you can _see_ it running! -<img src="img/deployed_dependency_update.png" alt="dependencies.io"> + However, looking at the freshly deployed code to check whether it still looks and behaves as expected is repetitive manual work, which means it is a prime candidate for automation. This is diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 0569bb281b9..2c2c6ecd30f 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -6,7 +6,7 @@ comments: false type: index --- -# GitLab CI/CD Examples +# GitLab CI/CD Examples **(FREE)** This page contains links to a variety of examples that can help you understand how to implement [GitLab CI/CD](../README.md) for your specific use case. @@ -33,7 +33,7 @@ The following table lists examples with step-by-step tutorials that are containe | npm with semantic-release | [Publish npm packages to the GitLab Package Registry using semantic-release](semantic-release.md). | | PHP with Laravel, Envoy | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md). | | PHP with npm, SCP | [Running Composer and npm scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md). | -| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | +| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | | Secrets management with Vault | [Authenticating and Reading Secrets With HashiCorp Vault](authenticating-with-hashicorp-vault/index.md). | ### Contributed examples @@ -58,7 +58,7 @@ separate example projects: Get started with GitLab CI/CD and your favorite programming language or framework by using a `.gitlab-ci.yml` [template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -When you create a `gitlab-ci.yml` file in the UI, you can +When you create a `.gitlab-ci.yml` file in the UI, you can choose one of these templates: - [Android (`Android.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Android.gitlab-ci.yml) @@ -76,7 +76,7 @@ choose one of these templates: - [dotNET Core (`dotNET-Core.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/dotNET-Core.gitlab-ci.yml) - [Elixir (`Elixir.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Elixir.gitlab-ci.yml) - [Flutter (`Flutter.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Flutter.gitlab-ci.yml) -- [goLang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) +- [Golang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) - [Gradle (`Gradle.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Gradle.gitlab-ci.yml) - [Grails (`Grails.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Grails.gitlab-ci.yml) - [iOS with fastlane (`iOS-Fastlane.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/iOS-Fastlane.gitlab-ci.yml) @@ -117,15 +117,16 @@ Note that older articles and videos may not reflect the state of the latest GitL For examples of setting up GitLab CI/CD for cloud-based environments, see: - [How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/blog/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/) -- [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) +- Video: [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) - [How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/blog/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/) - [How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/blog/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/) -- [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) +- Video: [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) +- Tutorial: [Set up a GitLab.com Civo Kubernetes integration with GitPod](https://gitlab.com/k33g_org/k33g_org.gitlab.io/-/issues/82) See also the following video overviews: -- [Kubernetes, GitLab, and Cloud Native](https://www.youtube.com/watch?v=d-9awBxEbvQ). -- [Deploying to IBM Cloud with GitLab CI/CD](https://www.youtube.com/watch?v=6ZF4vgKMd-g). +- Video: [Kubernetes, GitLab, and Cloud Native](https://www.youtube.com/watch?v=d-9awBxEbvQ) +- Video: [Deploying to IBM Cloud with GitLab CI/CD](https://www.youtube.com/watch?v=6ZF4vgKMd-g) ### Customer stories @@ -160,7 +161,9 @@ For examples of others who have implemented GitLab CI/CD, see: ### Migrating to GitLab from third-party CI tools -- [Migrating from Jenkins to GitLab](https://youtu.be/RlEVGOpYF5Y) +- [Migrating from CircleCI to GitLab](../migration/circleci.md) +- [Migrating from Jenkins to GitLab](../migration/jenkins.md) +- Video: [Migrating from Jenkins to GitLab](https://youtu.be/RlEVGOpYF5Y) ### Integrating GitLab CI/CD with other systems diff --git a/doc/ci/index.md b/doc/ci/index.md index 9175c20f580..87b259af62a 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -9,33 +9,23 @@ type: index # GitLab CI/CD **(FREE)** -GitLab CI/CD is a tool built into GitLab for software development -through the [continuous methodologies](introduction/index.md): +GitLab CI/CD is a tool for software development using the continuous methodologies: -- Continuous Integration (CI) -- Continuous Delivery (CD) -- Continuous Deployment (CD) +- [Continuous Integration (CI)](introduction/index.md#continuous-integration) +- [Continuous Delivery (CD)](introduction/index.md#continuous-delivery) +- [Continuous Deployment (CD)](introduction/index.md#continuous-deployment) NOTE: Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) -webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. +webcast to learn about continuous methods and how GitLab CI/CD can help you simplify and scale software development. -Continuous Integration works by pushing small code chunks to your -application's codebase hosted in a Git repository, and to every -push, run a pipeline of scripts to build, test, and validate the -code changes before merging them into the main branch. - -Continuous Delivery and Deployment consist of a step further CI, -deploying your application to production at every -push to the default branch of the repository. - -These methodologies allow you to catch bugs and errors early in -the development cycle, ensuring that all the code deployed to +Use GitLab CI/CD to catch bugs and errors early in +the development cycle. Ensure that all the code deployed to production complies with the code standards you established for your app. -GitLab can also automatically detect, build, test, deploy, and +GitLab CI/CD can automatically build, test, deploy, and monitor your applications by using [Auto DevOps](../topics/autodevops/index.md). For a complete overview of these methodologies and GitLab CI/CD, @@ -48,7 +38,7 @@ read the [Introduction to CI/CD with GitLab](introduction/index.md). <iframe src="https://www.youtube.com/embed/1iXFbchozdY" frameborder="0" allowfullscreen="true"> </iframe> </figure> -## Concepts +## GitLab CI/CD concepts GitLab CI/CD uses a number of concepts to describe and run your build and deploy. @@ -63,7 +53,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently. | | [Test cases](test_cases/index.md) | Create testing scenarios. | -## Configuration +## GitLab CI/CD configuration GitLab CI/CD supports numerous configuration options: @@ -82,21 +72,20 @@ GitLab CI/CD supports numerous configuration options: Certain operations can only be performed according to the [user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions. -## Feature set +## GitLab CI/CD features -Use the vast GitLab CI/CD to easily configure it for specific purposes. -Its feature set is listed on the table below according to DevOps stages. +GitLab CI/CD features, grouped by DevOps stage, include: | Feature | Description | |:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| | **Configure** | | | [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | -| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | +| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | |-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| | **Verify** | | | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [CI services](services/index.md) | Link Docker containers with your base image. | +| [CI services](services/index.md) | Link Docker containers with your base image. | | [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | | [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | | [Interactive Web Terminals](interactive_web_terminal/index.md) **(FREE SELF)** | Open an interactive web terminal to debug the running jobs. | @@ -107,7 +96,7 @@ Its feature set is listed on the table below according to DevOps stages. | [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | | [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | | [Canary Deployments](../user/project/canary_deployments.md) | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | -| [Deploy Boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | +| [Deploy boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | | [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | | [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | | [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | @@ -120,29 +109,29 @@ Its feature set is listed on the table below according to DevOps stages. | [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | | [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | -## Examples +## GitLab CI/CD examples -Find example project code and tutorials for using GitLab CI/CD with a variety of app frameworks, languages, and platforms -on the [CI Examples](examples/README.md) page. +See the [CI/CD examples](examples/README.md) page for example project code and tutorials for +using GitLab CI/CD with various: -## Administration **(FREE SELF)** +- App frameworks +- Languages +- Platforms -As a GitLab administrator, you can change the default behavior -of GitLab CI/CD for: +## GitLab CI/CD Administration -- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md). -- Specific projects, using [pipelines settings](pipelines/settings.md). +You can change the default behavior of GitLab CI/CD for: + +- An entire GitLab instance in the [CI/CD administration settings](../administration/index.md#cicd-settings). +- Specific projects in the [pipelines settings](pipelines/settings.md). See also: -- [How to enable or disable GitLab CI/CD](enable_or_disable_ci.md). -- Other [CI administration settings](../administration/index.md#continuous-integration-settings). +- [Enable or disable GitLab CI/CD in a project](enable_or_disable_ci.md). ## References -### Why GitLab CI/CD? - -Learn more about: +Learn more about GitLab CI/CD: - [Why you might choose GitLab CI/CD](https://about.gitlab.com/blog/2016/10/17/gitlab-ci-oohlala/). - [Reasons you might migrate from another platform](https://about.gitlab.com/blog/2016/07/22/building-our-web-app-on-gitlab-ci/). @@ -150,10 +139,10 @@ Learn more about: See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation. -### Breaking changes +### Major version changes (breaking) As GitLab CI/CD has evolved, certain breaking changes have -been necessary. These are: +been necessary. #### 13.0 diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 7e72bd44503..5724c56b096 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -5,12 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Interactive Web Terminals +# Interactive Web Terminals **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/50144) in GitLab 11.3. Interactive web terminals give the user access to a terminal in GitLab for -running one-off commands for their CI pipeline. Since this is giving the user +running one-off commands for their CI pipeline. You can think of it like a method for +debugging with SSH, but done directly from the job page. Since this is giving the user shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/) is deployed, some [security precautions](../../administration/integration/terminal.md#security) were taken to protect the users. diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md new file mode 100644 index 00000000000..70c22d566e5 --- /dev/null +++ b/doc/ci/jobs/ci_job_token.md @@ -0,0 +1,165 @@ +--- +stage: Verify +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 +--- + +# GitLab CI/CD job token + +When a pipeline job is about to run, GitLab generates a unique token and injects it as the +[`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md). + +You can use a GitLab CI/CD job token to authenticate with specific API endpoints: + +- Packages: + - [Package Registry](../../user/packages/package_registry/index.md). To push to the + Package Registry, you can use [deploy tokens](../../user/project/deploy_tokens/index.md). + - [Container Registry](../../user/packages/container_registry/index.md) + (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). + - [Container Registry API](../../api/container_registry.md) + (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled). +- [Get job artifacts](../../api/job_artifacts.md#get-job-artifacts). +- [Get job token's job](../../api/jobs.md#get-job-tokens-job). +- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter. +- [Release creation](../../api/releases/index.md#create-a-release). +- [Terraform plan](../../user/infrastructure/index.md). + +The token has the same permissions to access the API as the user that triggers the +pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions). + +The token is valid only while the pipeline job runs. After the job finishes, you can't +use the token anymore. + +A job token can access a project's resources without any configuration, but it might +give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) +to redesign the feature for more strategic control of the access permissions. + +You can also use the job token to authenticate and clone a repository from a private project +in a CI/CD job: + +```shell +git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project> +``` + +## GitLab CI/CD job token security + +To make sure that this token doesn't leak, GitLab: + +- Masks the job token in job logs. +- Grants permissions to the job token only when the job is running. + +To make sure that this token doesn't leak, you should also configure +your [runners](../runners/index.md) to be secure. Avoid: + +- Using Docker's `privileged` mode if the machines are re-used. +- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs + run on the same machine. + +If you have an insecure GitLab Runner configuration, you increase the risk that someone +tries to steal tokens from other jobs. + +## Limit GitLab CI/CD job token access + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. +> - [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-ci-job-token-scope-limit). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +You can limit the access scope of a project's CI/CD job token to increase the +job token's security. A job token might give extra permissions that aren't necessary +to access specific private resources. Limiting the job token access scope reduces the risk of a leaked +token being used to access private data that the user associated to the job can access. + +Control the job token access scope with an allowlist of other projects authorized +to be accessed by authenticating with the current project's job token. By default +the token scope only allows access to the same project where the token comes from. +Other projects can be added and removed by maintainers with access to both projects. + +This setting is enabled by default for all new projects, and disabled by default in projects +created before GitLab 14.1. It is strongly recommended that project maintainers enable this +setting at all times, and configure the allowlist for cross-project access if needed. + +For example, when the setting is enabled, jobs in a pipeline in project `A` have +a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token +to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`. +If project `B` is public or internal, it doesn't need to be added to the allowlist. +The job token scope is only for controlling access to private projects. + +To enable and configure the job token scope limit: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Toggle **Limit CI_JOB_TOKEN access** to enabled. +1. (Optional) Add existing projects to the token's access scope. The user adding a + project must have the [maintainer role](../../user/permissions.md) in both projects. + +If the job token scope limit is disabled, the token can potentially be used to authenticate +API requests to all projects accessible to the user that triggered the job. + +There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve +the feature with more strategic control of the access permissions. + +### Enable or disable CI job token scope limit **(FREE SELF)** + +The GitLab CI/CD job token access scope limit 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(:ci_scoped_job_token) +``` + +To disable it: + +```ruby +Feature.disable(:ci_scoped_job_token) +``` + +## Trigger a multi-project pipeline by using a CI job token + +> `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4. + +You can use the `CI_JOB_TOKEN` to trigger [multi-project pipelines](../pipelines/multi_project_pipelines.md) +from a CI/CD job. A pipeline triggered this way creates a dependent pipeline relation +that is visible on the [pipeline graph](../pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization). + +For example: + +```yaml +trigger_pipeline: + stage: deploy + script: + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + rules: + - if: $CI_COMMIT_TAG +``` + +If you use the `CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) +in a pipeline triggered this way, [the value is `pipeline` (not `triggered`)](../triggers/index.md#authentication-tokens). + +## Download an artifact from a different pipeline **(PREMIUM)** + +> `CI_JOB_TOKEN` for artifacts download with the API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5. + +You can use the `CI_JOB_TOKEN` to access artifacts from a job created by a previous +pipeline. You must specify which job you want to retrieve the artifacts from: + +```yaml +build_submodule: + stage: test + script: + - apt update && apt install -y unzip + - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" + - unzip artifacts.zip +``` + +Read more about the [jobs artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive). diff --git a/doc/ci/jobs/img/job_group_v12_10.png b/doc/ci/jobs/img/job_group_v12_10.png Binary files differdeleted file mode 100644 index 27e6bfbfc0f..00000000000 --- a/doc/ci/jobs/img/job_group_v12_10.png +++ /dev/null diff --git a/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png b/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png Binary files differnew file mode 100644 index 00000000000..8dbb118406c --- /dev/null +++ b/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png diff --git a/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png b/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png Binary files differnew file mode 100644 index 00000000000..28be633770b --- /dev/null +++ b/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png diff --git a/doc/ci/jobs/img/pipeline_incremental_rollout.png b/doc/ci/jobs/img/pipeline_incremental_rollout.png Binary files differdeleted file mode 100644 index b3498e9a5a5..00000000000 --- a/doc/ci/jobs/img/pipeline_incremental_rollout.png +++ /dev/null diff --git a/doc/ci/jobs/img/pipelines_grouped.png b/doc/ci/jobs/img/pipelines_grouped.png Binary files differdeleted file mode 100644 index 82814754747..00000000000 --- a/doc/ci/jobs/img/pipelines_grouped.png +++ /dev/null diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index aa12e1181cb..54704d5574b 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -58,7 +58,7 @@ In each place, if you hover over the failed job you can see the reason it failed  -In [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814) and later, +In [GitLab 10.8 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814), you can also see the reason it failed on the Job detail page. ## The order of jobs in a pipeline @@ -99,7 +99,7 @@ You can recognize when a pipeline has grouped jobs if you don't see the retry or cancel button inside them. Hovering over them shows the number of grouped jobs. Click to expand them. - + To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/index.md), separate each job name with a number and one of the following: @@ -129,9 +129,7 @@ build ruby 3/3: - echo "ruby3" ``` -In the pipeline, the result is a group named `build ruby` with three jobs: - - +The pipeline graph displays a group named `build ruby` with three jobs. The jobs are ordered by comparing the numbers from left to right. You usually want the first number to be the index and the second number to be the total. @@ -179,7 +177,7 @@ For example, if you start rolling out new code and: - Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline and [rolling](../environments/index.md#retry-or-roll-back-a-deployment) back to the last stable version. - + ## Expand and collapse job log sections diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index b8b05426297..ad2bbbc883c 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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 --- @@ -225,7 +225,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: | `pipeline` | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](../yaml/index.md#trigger) keyword. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | -| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). | +| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | | `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | @@ -290,6 +290,35 @@ You can use the `$` character for both variables and paths. For example, if the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$` is interpreted as being part of a path. +## Reuse rules in different jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3. + +Use [`!reference` tags](../yaml/index.md#reference-tags) to reuse rules in different +jobs. You can combine `!reference` rules with regular job-defined rules: + +```yaml +.default_rules: + rules: + - if: $CI_PIPELINE_SOURCE == "schedule" + when: never + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +job1: + rules: + - !reference [.default_rules, rules] + script: + - echo "This job runs for the default branch, but not schedules." + +job2: + rules: + - !reference [.default_rules, rules] + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: + - echo "This job runs for the default branch, but not schedules." + - echo "It also runs for merge requests." +``` + ## Specify when jobs run with `only` and `except` You can use [`only`](../yaml/index.md#only--except) and [`except`](../yaml/index.md#only--except) @@ -306,7 +335,7 @@ to control when to add jobs to pipelines. In the following example, `job` runs only for: - Git tags -- [Triggers](../triggers/index.md#trigger-token) +- [Triggers](../triggers/index.md#authentication-tokens) - [Scheduled pipelines](../pipelines/schedules.md) ```yaml diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index c3b0cd79d2c..07b4cd80d6a 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -5,11 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Optimizing GitLab for large repositories +# Optimize GitLab for large repositories **(FREE)** Large repositories consisting of more than 50k files in a worktree -often require special consideration because of -the time required to clone and check out. +may require more optimizations beyond +[pipeline efficiency](../pipelines/pipeline_efficiency.md) +because of the time required to clone and check out. GitLab and GitLab Runner handle this scenario well but require optimized configuration to efficiently perform its @@ -251,6 +252,8 @@ and does not require us to update each `.gitlab-ci.yml`. ## Pre-clone step +> [An issue exists](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/463) to remove the need for this optimization. + For very active repositories with a large number of references and files, you can also optimize your CI jobs by seeding repository data with GitLab Runner's [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 4e3ac8b9e93..e01bd6b79ff 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -3,11 +3,8 @@ stage: Verify 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 --- -<!-- markdownlint-disable MD044 --> -<!-- vale gitlab.Spelling = NO --> -# Validate .gitlab-ci.yml syntax with the CI Lint tool -<!-- markdownlint-enable MD044 --> -<!-- vale gitlab.Spelling = YES --> + +# Validate `.gitlab-ci.yml` syntax with the CI Lint tool If you want to test the validity of your GitLab CI/CD configuration before committing the changes, you can use the CI Lint tool. This tool checks for syntax and logical diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 106f5b3d819..efaae873588 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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 comments: false type: index, howto @@ -121,11 +121,11 @@ stages: - test - deploy -job 1: +job1: stage: build script: make build dependencies -job 2: +job2: stage: build script: make build artifacts @@ -216,12 +216,12 @@ jobs: Example of the same workflow using `rules` in GitLab CI/CD: ```yaml -deploy_prod: +deploy: stage: deploy script: - - echo "Deploy to production server" + - echo "Deploy job" rules: - - if: '$CI_COMMIT_BRANCH == "main"' + - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^rc-/' ``` ### Caching diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 1a987a0ce47..925dff8751c 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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 comments: false type: index, howto @@ -130,7 +130,7 @@ There are some important differences in the way runners work in comparison to ag - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/runners_scope.md). They self-select jobs from the scopes you've defined automatically. -- You can also [use tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and +- You can also [use tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). @@ -199,7 +199,7 @@ GitLab takes advantage of our connected ecosystem to automatically pull these ki your Merge Requests, pipeline details pages, and other locations. You may find that you actually don't need to configure anything to have these appear. -If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../index.md#feature-set) has the full list +If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../index.md#gitlab-cicd-features) has the full list of bundled features and links to the documentation for each. ### Templates @@ -230,7 +230,7 @@ and is meant to be a mapping of concepts there to concepts in GitLab. The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/index.md) to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users). -We also support using [tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs +We also support using [tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) to direct different jobs to different runners (execution agents). The `agent` section also allows you to define which Docker images should be used for execution, for which we use diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 7132d47d324..10a6d34b076 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -56,7 +56,7 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint > - [Moved to **CI/CD > Editor**](https://gitlab.com/gitlab-org/gitlab/-/issues/263141) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.12. -To view a visualization of your `gitlab-ci.yml` configuration, in your project, +To view a visualization of your `.gitlab-ci.yml` configuration, in your project, go to **CI/CD > Editor**, and then select the **Visualize** tab. The visualization shows all stages and jobs. Any [`needs`](../yaml/index.md#needs) relationships are displayed as lines connecting jobs together, showing the diff --git a/doc/ci/pipelines/img/manual_pipeline_v14_2.png b/doc/ci/pipelines/img/manual_pipeline_v14_2.png Binary files differnew file mode 100644 index 00000000000..df1c2a4760a --- /dev/null +++ b/doc/ci/pipelines/img/manual_pipeline_v14_2.png diff --git a/doc/ci/pipelines/img/pipelines.png b/doc/ci/pipelines/img/pipelines.png Binary files differdeleted file mode 100644 index a604fcb2587..00000000000 --- a/doc/ci/pipelines/img/pipelines.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png Binary files differdeleted file mode 100644 index f2f38979e18..00000000000 --- a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png Binary files differnew file mode 100644 index 00000000000..b0e9f63f743 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 22f18235f99..1eacc799636 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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 disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference @@ -122,6 +122,7 @@ you can filter the pipeline list by: - Branch name - Status ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) - Tag ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) +- Source ([GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338347)) [Starting in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/26621), you can change the pipeline column to display the pipeline ID or the pipeline IID. @@ -170,9 +171,6 @@ variables: You cannot set job-level variables to be pre-filled when you run a pipeline manually. -Pre-filled variables do not show up when the CI/CD configuration is [external to the project](settings.md#specify-a-custom-cicd-configuration-file). -See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336184) for more details. - ### Run a pipeline by using a URL query string > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24146) in GitLab 12.5. @@ -212,11 +210,11 @@ allow you to require manual interaction before moving forward in the pipeline. You can do this straight from the pipeline graph. Just click the play button to execute that particular job. -For example, your pipeline might start automatically, but it requires manual action to -[deploy to production](../environments/index.md#configure-manual-deployments). In the example below, the `production` -stage has a job with a manual action. +For example, your pipeline can start automatically, but require a manual action to +[deploy to production](../environments/index.md#configure-manual-deployments). +In the example below, the `production` stage has a job with a manual action: - + #### Start multiple manual actions in a stage @@ -348,9 +346,9 @@ all the jobs in the pipeline. You can group the jobs by: -- Stage, which arranges jobs in the same stage together in the same column. +- Stage, which arranges jobs in the same stage together in the same column: -  +  - [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges jobs based on their [`needs`](../yaml/index.md#needs) dependencies. @@ -361,21 +359,16 @@ you visualize the entire pipeline, including all cross-project inter-dependencie ### View job dependencies in the pipeline graph > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298973) in GitLab 13.12. -> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 13.12. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.2. -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs) dependencies. Jobs in the leftmost column run first, and jobs that depend on them are grouped in the next columns. -For example, `build-job2` depends only on jobs in the first column, so it displays -in the second column from the left. `deploy-job2` depends on jobs in both the first +For example, `test-job1` depends only on jobs in the first column, so it displays +in the second column from the left. `deploy-job1` depends on jobs in both the first and second column and displays in the third column:  diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index 3007d91d1b4..d31ddcf736e 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -273,7 +273,7 @@ upstream_bridge: > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) to GitLab Free in 12.4. -When you use the [`CI_JOB_TOKEN` to trigger pipelines](../triggers/index.md#ci-job-token), +When you use the [`CI_JOB_TOKEN` to trigger pipelines](../jobs/ci_job_token.md), GitLab recognizes the source of the job token. The pipelines become related, so you can visualize their relationships on pipeline graphs. diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md index b266a721d11..71f778d81b3 100644 --- a/doc/ci/pipelines/parent_child_pipelines.md +++ b/doc/ci/pipelines/parent_child_pipelines.md @@ -61,7 +61,8 @@ microservice_a: include: path/to/microservice_a.yml ``` -You can include multiple files when composing a child pipeline: +You can include multiple files when defining a child pipeline. The child pipeline's +configuration is composed of all configuration files merged together: ```yaml microservice_a: @@ -156,15 +157,11 @@ build a matrix of targets and architectures. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). -<!-- vale gitlab.Spelling = NO --> - We also have an example project using [Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like -[Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). - -<!-- vale gitlab.Spelling = NO --> +[Dhall](https://dhall-lang.org/) or [ytt](https://get-ytt.io/). The artifact path is parsed by GitLab, not the runner, so the path must match the syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 91560a0420f..5c3cdd0633e 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -28,6 +28,7 @@ The easiest indicators to check for inefficient pipelines are the runtimes of th stages, and the total runtime of the pipeline itself. The total pipeline duration is heavily influenced by the: +- [Size of the repository](../large_repositories/index.md) - Total number of stages and jobs. - Dependencies between jobs. - The ["critical path"](#directed-acyclic-graphs-dag-visualization), which represents diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index b48c62dccc5..94d7e317104 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -124,7 +124,7 @@ If the CI/CD configuration file is on an external site, the URL must end with `. If the CI/CD configuration file is in a different project: -- The file must exist on its default branch. +- The file must exist on its default branch, or specify the branch as refname. - The path must be relative to the root directory in the other project. - The path must include the group and project name at the end. @@ -132,6 +132,7 @@ For example: - `.gitlab-ci.yml@mygroup/another-project` - `my/path/.my-custom-file.yml@mygroup/another-project` +- `my/path/.my-custom-file.yml@mygroup/another-project:refname` If the configuration file is in a separate project, you can more set more granular permissions. For example: diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 257e170b0a5..e2381238318 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -7,8 +7,7 @@ type: reference # Get started with GitLab CI/CD **(FREE)** -Use this document to get started with -GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). +Use this document to get started with [GitLab CI/CD](../index.md). Before you start, make sure you have: @@ -126,7 +125,7 @@ The pipeline starts when the commit is committed. ```yaml default: - image: ruby:2.7.2 + image: ruby:2.7.4 ``` This command tells the runner to use a Ruby image from Docker Hub @@ -141,8 +140,22 @@ The pipeline starts when the commit is committed. [CI Lint tool](../lint.md), which is available in every project. - You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to view a graphical representation of your `.gitlab-ci.yml` file. -- For the complete `.gitlab-ci.yml` syntax, see - [the `.gitlab-ci.yml` reference topic](../yaml/index.md). +- Each job contains scripts and stages: + - The [`default`](../yaml/index.md#custom-default-keyword-values) keyword is for + custom defaults, for example with [`before_script`](../yaml/index.md#before_script) + and [`after_script`](../yaml/index.md#after_script). + - [`stage`](../yaml/index.md#stage) describes the sequential execution of jobs. + Jobs in a single stage run in parallel as long as there are available runners. + - Use [Directed Acyclic Graphs (DAG)](../directed_acyclic_graph/index.md) keywords + to run jobs out of stage order. +- You can set additional configuration to customize how your jobs and stages perform: + - Use the [`rules`](../yaml/index.md#rules) keyword to specify when to run or skip jobs. + The `only` and `except` legacy keywords are still supported, but can't be used + with `rules` in the same job. + - Keep information across jobs and stages persistent in a pipeline with [`cache`](../yaml/index.md#cache)) + and [`artifacts`](../yaml/index.md#artifacts). These keywords are ways to store + dependencies and job output, even when using ephemeral runners for each job. +- For the complete `.gitlab-ci.yml` syntax, see [the full `.gitlab-ci.yml` reference topic](../yaml/index.md). ### View the status of your pipeline and jobs diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 8af04388f92..1b926d506c4 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -57,7 +57,7 @@ The process of configuring Review Apps is as follows: 1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below). 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a runner to do deployment. -1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/index.md) `${CI_COMMIT_REF_NAME}` +1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/index.md) `${CI_COMMIT_REF_SLUG}` to create dynamic environments and restrict it to run only on branches. Alternatively, you can get a YML template for this job by [enabling review apps](#enable-review-apps-button) for your project. 1. Optionally, set a job that [manually stops](../environments/index.md#stop-an-environment) the Review Apps. diff --git a/doc/ci/runners/build_cloud/macos/environment.md b/doc/ci/runners/build_cloud/macos/environment.md index e84b7d0a207..5336890b931 100644 --- a/doc/ci/runners/build_cloud/macos/environment.md +++ b/doc/ci/runners/build_cloud/macos/environment.md @@ -4,12 +4,12 @@ group: Runner 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 --- -# VM instances and images for Build Cloud for macOS +# VM instances and images for Build Cloud for macOS When you use the Build Cloud for macOS: -- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. -- The VM is active only for the duration of the job and immediately deleted. +- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. +- The VM is active only for the duration of the job and immediately deleted. ## VM types diff --git a/doc/ci/runners/build_cloud/macos_build_cloud.md b/doc/ci/runners/build_cloud/macos_build_cloud.md index 1400c7e08db..794bc2e597d 100644 --- a/doc/ci/runners/build_cloud/macos_build_cloud.md +++ b/doc/ci/runners/build_cloud/macos_build_cloud.md @@ -12,11 +12,11 @@ of all the capabilities of the GitLab single DevOps platform and not have to man build environment. Build Cloud runners for macOS are in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) -and shouldn't be relied upon for mission-critical production jobs. +and shouldn't be relied upon for mission-critical production jobs. ## Quickstart -To start using Build Cloud for macOS Beta, you must submit an access request issue. After your +To start using Build Cloud for macOS Beta, you must submit an access request [issue](https://gitlab.com/gitlab-com/macos-buildcloud-runners-beta/-/issues/new?issuable_template=beta_access_request). After your access has been granted and your build environment configured, you must configure your `.gitlab-ci.yml` pipeline file: diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 2f845a05a4e..13897b934c5 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Configuring runners +# Configuring runners **(FREE)** If you have installed your own runners, you can configure and secure them in GitLab. @@ -107,10 +107,10 @@ We're always looking for contributions that can mitigate these ### Reset the runner registration token for a project If you think that a registration token for a project was revealed, you should -reset it. A token can be used to register another runner for the project. That new runner -may then be used to obtain the values of secret variables or to clone project code. +reset it. A registration token can be used to register another runner for the project. +That new runner may then be used to obtain the values of secret variables or to clone project code. -To reset the token: +To reset the registration token: 1. Go to the project's **Settings > CI/CD**. 1. Expand the **General pipelines settings** section. @@ -124,6 +124,16 @@ any new runners to the project. If you are using any tools to provision and register new runners, the tokens used in those tools should be updated to reflect the value of the new token. +### Reset the runner authentication token + +If you think that an authentication token for a runner was revealed, you should +reset it. An attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). + +To reset the authentication token, [unregister the runner](https://docs.gitlab.com/runner/commands/#gitlab-runner-unregister) +and then [register](https://docs.gitlab.com/runner/commands/#gitlab-runner-register) it again. + +To verify that the previous authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). + ## Determine the IP address of a runner > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17286) in GitLab 10.6. @@ -142,7 +152,7 @@ different places. To view the IP address of a shared runner you must have admin access to the GitLab instance. To determine this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Runners**. 1. Find the runner in the table and view the **IP Address** column. @@ -159,13 +169,13 @@ project.  -## Use tags to limit the number of jobs using the runner +## Use tags to control which jobs a runner can run You must set up a runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be problematic for large amounts of projects, if it weren't for tags. -GitLab CI tags are not the same as Git tags. GitLab CI tags are associated with runners. +GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. By tagging a runner for the types of jobs it can handle, you can make sure @@ -174,6 +184,8 @@ shared runners will [only run the jobs they are equipped to run](../yaml/index.m For instance, at GitLab we have runners tagged with `rails` if they contain the appropriate dependencies to run Rails test suites. +### Set a runner to run untagged jobs + When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** [tagged jobs](../yaml/index.md#tags). To change this, you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project. @@ -228,6 +240,48 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. +### Use tags to run jobs on different platforms + +You can use tags to run different jobs on different platforms. For +example, if you have an OS X runner with tag `osx` and a Windows runner with tag +`windows`, you can run a job on each platform: + +```yaml +windows job: + stage: + - build + tags: + - windows + script: + - echo Hello, %USERNAME%! + +osx job: + stage: + - build + tags: + - osx + script: + - echo "Hello, $USER!" +``` + +### Use CI/CD variables in tags + +> Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742). + +You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: + +```yaml +variables: + KUBERNETES_RUNNER: kubernetes + + job: + tags: + - docker + - $KUBERNETES_RUNNER + script: + - echo "Hello runner selector feature" +``` + ## Configure runner behavior with variables You can use [CI/CD variables](../variables/index.md) to configure runner Git behavior @@ -546,7 +600,7 @@ the following stages: | Variable | Description | |---------------------------------|--------------------------------------------------------| | `ARTIFACT_DOWNLOAD_ATTEMPTS` | Number of attempts to download artifacts running a job | -| `EXECUTOR_JOB_SECTION_ATTEMPTS` | [In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) and later, the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | +| `EXECUTOR_JOB_SECTION_ATTEMPTS` | In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450), the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | | `GET_SOURCES_ATTEMPTS` | Number of attempts to fetch sources running a job | | `RESTORE_CACHE_ATTEMPTS` | Number of attempts to restore the cache running a job | diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 6642913a9d8..9acca60c4b4 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Build Cloud runners +# GitLab Build Cloud runners **(FREE)** If you are using self-managed GitLab or you want to use your own runners on GitLab.com, you can [install and configure your own runners](https://docs.gitlab.com/runner/install/). diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 2af373384d2..b16957ae83c 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# The scope of runners +# The scope of runners **(FREE)** Runners are available based on who you want to have access: @@ -168,7 +168,7 @@ You must have the [Owner role](../../user/permissions.md#group-members-permissio | Attribute | Description | | ------------ | ----------- | - | Type | Displays the runner type: `group` or `specific`, together with the optional states `locked` and `paused` | + | Type | Displays the runner type: `group` or `specific`, and the optional state `paused` | | Runner token | Token used to identify the runner, and that the runner uses to communicate with the GitLab instance | | Description | Description given to the runner when it was created | | Version | GitLab Runner version | @@ -242,10 +242,10 @@ You can configure a specific runner so it is "locked" and cannot be enabled for This setting can be enabled when you first [register a runner](https://docs.gitlab.com/runner/register/), but can also be changed later. -To lock or unlock a runner: +To lock or unlock a specific runner: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the runner you want to lock or unlock. Make sure it's enabled. +1. Find the specific runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners. 1. Click the pencil button. 1. Check the **Lock to current projects** option. 1. Click **Save changes**. diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index d3c34a6922e..898d310598f 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -95,7 +95,7 @@ To configure your Vault server: ## Use Vault secrets in a CI job **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4 and GitLab Runner 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4 and GitLab Runner 13.4. After [configuring your Vault server](#configure-your-vault-server), you can use the secrets stored in Vault by defining them with the `vault` keyword: diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 558f53a9535..5ac66846ab7 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Use GitLab as a microservice +# Use GitLab as a microservice **(FREE)** Many applications need to access JSON APIs, so application tests might need access to APIs too. The following example shows how to use GitLab as a microservice to give @@ -24,10 +24,9 @@ tests access to the GitLab API. GITLAB_ROOT_PASSWORD: "password" # to access the api with user root:password ``` -1. To set values for the `GITLAB_HTTPS` and `GITLAB_ROOT_PASSWORD`, - [assign them to a variable in the user interface](../variables/index.md#add-a-cicd-variable-to-a-project). - Then assign that variable to the corresponding variable in your - `.gitlab-ci.yml` file. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md#). Then, commands in `script:` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`. diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index c7891998a37..4114833d1c8 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -6,7 +6,7 @@ comments: false type: index --- -# Services +# Services **(FREE)** The `services` keyword defines a Docker image that runs during a `job` linked to the Docker image that the image keyword defines. This allows @@ -186,6 +186,34 @@ following these rules: To override the default behavior, you can [specify a service alias](#available-settings-for-services). +### Connecting services + +You can use inter-dependent services with complex jobs, like end-to-end tests where an +external API needs to communicate with its own database. + +For example, for an end-to-end test for a front-end application that uses an API, and where the API needs a database: + +```yaml +end-to-end-tests: + image: node:latest + services: + - name: selenium/standalone-firefox:${FIREFOX_VERSION} + alias: firefox + - name: registry.gitlab.com/organization/private-api:latest + alias: backend-api + - postgres:9.6.19 + variables: + FF_NETWORK_PER_BUILD: 1 + POSTGRES_PASSWORD: supersecretpassword + BACKEND_POSTGRES_HOST: postgres + script: + - npm install + - npm test +``` + +For this solution to work, you must use +[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). + ## Passing CI/CD variables to services You can also pass custom CI/CD [variables](../variables/index.md) @@ -311,6 +339,34 @@ services: The syntax of `command` is similar to [Dockerfile's `CMD`](https://docs.docker.com/engine/reference/builder/#cmd). +## Using `services` with `docker run` (Docker-in-Docker) side-by-side + +Containers started with `docker run` can also connect to services provided by GitLab. + +When booting the service is expensive or time consuming, you can use +this technique to run tests from different client environments, +while only booting up the tested service once. + +```yaml +access-service: + stage: build + image: docker:19.03.1 + services: + - docker:dind # necessary for docker run + - tutum/wordpress:latest + variables: + FF_NETWORK_PER_BUILD: "true" # activate container-to-container networking + script: | + docker run --rm --name curl \ + --volume "$(pwd)":"$(pwd)" \ + --workdir "$(pwd)" \ + --network=host \ + curlimages/curl:7.74.0 curl "http://tutum-wordpress" +``` + +For this solution to work, you must use +[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). + ## How Docker integration works Below is a high level overview of the steps performed by Docker during job diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index c691a6ef33d..d0ac123ba62 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using MySQL +# Using MySQL **(FREE)** Many applications depend on MySQL as their database, and you may need it for your tests to run. @@ -16,11 +16,9 @@ If you want to use a MySQL container, you can use [GitLab Runner](../runners/ind This example shows you how to set a username and password that GitLab uses to access the MySQL container. If you do not set a username and password, you must use `root`. -1. [Create CI/CD variables](../variables/index.md#custom-cicd-variables) for your - MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**, - and clicking **Add Variable**. - - This example uses `$MYSQL_DB` and `$MYSQL_PASS` as the keys. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md). 1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file: @@ -39,8 +37,8 @@ This example shows you how to set a username and password that GitLab uses to ac ```yaml variables: # Configure mysql environment variables (https://hub.docker.com/_/mysql/) - MYSQL_DATABASE: $MYSQL_DB - MYSQL_ROOT_PASSWORD: $MYSQL_PASS + MYSQL_DATABASE: $MYSQL_DATABASE + MYSQL_ROOT_PASSWORD: $MYSQL_ROOT_PASSWORD ``` The MySQL container uses `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` to connect to the database. diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 8d14e4795d2..62838e04969 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using PostgreSQL +# Using PostgreSQL **(FREE)** As many applications depend on PostgreSQL as their database, you eventually need it in order for your tests to run. Below you are guided how to @@ -16,6 +16,10 @@ do this with the Docker and Shell executors of GitLab Runner. If you're using [GitLab Runner](../runners/index.md) with the Docker executor, you basically have everything set up already. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md). + First, in your `.gitlab-ci.yml` add: ```yaml @@ -23,25 +27,19 @@ services: - postgres:12.2-alpine variables: - POSTGRES_DB: nice_marmot - POSTGRES_USER: runner - POSTGRES_PASSWORD: "" + POSTGRES_DB: $POSTGRES_DB + POSTGRES_USER: $POSTGRES_USER + POSTGRES_PASSWORD: $POSTGRES_PASSWORD POSTGRES_HOST_AUTH_METHOD: trust ``` -To set values for the `POSTGRES_DB`, `POSTGRES_USER`, -`POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`, -[assign them to a CI/CD variable in the user interface](../variables/index.md#custom-cicd-variables), -then assign that variable to the corresponding variable in your -`.gitlab-ci.yml` file. - And then configure your application to use the database, for example: ```yaml Host: postgres -User: runner -Password: '' -Database: nice_marmot +User: $PG_USER +Password: $PG_PASSWORD +Database: $PG_DB ``` If you're wondering why we used `postgres` for the `Host`, read more at diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index d8c7b805864..a3446fc2677 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using Redis +# Using Redis **(FREE)** As many applications depend on Redis as their key-value store, you eventually need it in order for your tests to run. Below you are guided how to diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index 880473d402d..a2dd4ac91d5 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -14,8 +14,8 @@ tag) with an API call. The following methods of authentication are supported: -- [Trigger token](#trigger-token) -- [CI job token](#ci-job-token) +- Trigger tokens: A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). +- [CI job tokens](../jobs/ci_job_token.md). If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`, @@ -28,71 +28,6 @@ depending on which trigger method is used. This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/index.md#only--except). -### Trigger token - -A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). - -WARNING: -Passing plain text tokens in public projects is a security issue. Potential -attackers can impersonate the user that exposed their trigger token publicly in -their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md) -to protect trigger tokens. - -### CI job token - -You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/index.md#predefined-cicd-variables) (used to authenticate -with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases. - -#### When used with multi-project pipelines - -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [made available](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) in all tiers in GitLab 12.4. - -This way of triggering can only be used when invoked inside `.gitlab-ci.yml`, -and it creates a dependent pipeline relation visible on the -[pipeline graph](../pipelines/multi_project_pipelines.md). For example: - -```yaml -trigger_pipeline: - stage: deploy - script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" - rules: - - if: $CI_COMMIT_TAG -``` - -Pipelines triggered that way also expose a special variable: -`CI_PIPELINE_SOURCE=pipeline`. - -Read more about the [pipelines trigger API](../../api/pipeline_triggers.md). - -#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** - -> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5. - -With the introduction of dependencies between different projects, one of -them may need to access artifacts created by a previous one. This process -must be granted for authorized accesses, and it can be done using the -`CI_JOB_TOKEN` variable that identifies a specific job. For example: - -```yaml -build_submodule: - image: debian - stage: test - script: - - apt update && apt install -y unzip - - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" - - unzip artifacts.zip - rules: - - if: $CI_COMMIT_TAG -``` - -This allows you to use that for multi-project pipelines and download artifacts -from any project to which you have access as this follows the same principles -with the [permission model](../../user/permissions.md#job-permissions). - -Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive). - ## Adding a new trigger Go to your @@ -106,6 +41,12 @@ overview of the time the triggers were last used.  +WARNING: +Passing plain text tokens in public projects is a security issue. Potential +attackers can impersonate the user that exposed their trigger token publicly in +their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md) +to protect trigger tokens. + ## Revoking a trigger You can revoke a trigger any time by going at your project's diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index df9b20d1708..827a89fa99c 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -29,7 +29,7 @@ with your editor of choice. ### Verify syntax with CI Lint tool The [CI Lint tool](lint.md) is a simple way to ensure the syntax of a CI/CD configuration -file is correct. Paste in full `gitlab-ci.yml` files or individual jobs configuration, +file is correct. Paste in full `.gitlab-ci.yml` files or individual jobs configuration, to verify the basic syntax. When a `.gitlab-ci.yml` file is present in a project, you can also use the CI Lint @@ -49,7 +49,7 @@ and check if their values are what you expect. ## GitLab CI/CD documentation -The [complete `gitlab-ci.yml` reference](yaml/index.md) contains a full list of +The [complete `.gitlab-ci.yml` reference](yaml/index.md) contains a full list of every keyword you may need to use to configure your pipelines. You can also look at a large number of pipeline configuration [examples](examples/index.md) diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index a00b8b678ec..fa4bc6e39fb 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -20,6 +20,15 @@ You can use [predefined CI/CD variables](#predefined-cicd-variables) or define c - [Group CI/CD variables](#add-a-cicd-variable-to-a-group). - [Instance CI/CD variables](#add-a-cicd-variable-to-an-instance). +NOTE: +Variables set in the GitLab UI are **not** passed down to [service containers](../docker/using_docker_images.md). +To set them, assign them to variables in the UI, then re-assign them in your `.gitlab-ci.yml`: + +```yaml +variables: + SA_PASSWORD: $SA_PASSWORD +``` + > For more information about advanced use of GitLab CI/CD: > > - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Get to productivity faster with these [7 advanced GitLab CI workflow hacks](https://about.gitlab.com/webcast/7cicd-hacks/) @@ -116,7 +125,7 @@ Use the [`value` and `description`](../yaml/index.md#prefill-variables-in-manual keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually). -### Use variables or `$` in other variables +### Use variables in other variables You can use variables inside other variables: @@ -129,7 +138,9 @@ job: - 'eval "$LS_CMD"' # Executes 'ls -al' ``` -If you do not want the `$` interpreted as the start of a variable, use `$$` instead: +#### Use the `$` character in variables + +If you do not want the `$` character interpreted as the start of a variable, use `$$` instead: ```yaml job: @@ -228,7 +239,7 @@ You can define instance variables via the UI or [API](../../api/instance_level_c To add an instance variable: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD** and expand the **Variables** section. 1. Select the **Add variable** button, and fill in the details: @@ -295,6 +306,26 @@ echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" ``` +#### Store multiple values in one variable + +It is not possible to create a CI/CD variable that is an array of values, but you +can use shell scripting techniques for similar behavior. + +For example, you can store multiple variables separated by a space in a variable, +then loop through the values with a script: + +```yaml +job1: + variables: + FOLDERS: src test docs + script: + - | + for FOLDER in $FOLDERS + do + echo "The path is root/${FOLDER}" + done +``` + ### Mask a CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13784) in GitLab 11.10 diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index b5999a555c9..c8688d2433e 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -41,7 +41,8 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | | `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#debug-logging) is enabled. | | `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | -| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_PASSWORD` | 13.7 | all | The password to pull images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_SERVER` | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | | `CI_DEPENDENCY_PROXY_USER` | 13.7 | all | The username to pull images through the Dependency Proxy. | @@ -62,7 +63,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. | | `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. | -| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../../api/index.md#gitlab-cicd-job-token). The token is valid as long as the job is running. | +| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. | | `CI_JOB_URL` | 11.1 | 0.5 | The job details URL. | | `CI_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://tools.ietf.org/html/rfc3339#appendix-A) format. | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. | @@ -82,7 +83,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | | `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) of the job. | -| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-`. Use in URLs and domain names. | +| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | | `CI_PROJECT_PATH` | 8.10 | 0.5 | The project namespace with the project name included. | | `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. | | `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 8009687dbca..0f9339657fe 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -26,7 +26,7 @@ There are two places defined variables can be used. On the: |:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `environment:url` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | | `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | -| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | +| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/>- `CI_ENVIRONMENT_URL`<br/>- [Persisted variables](#persisted-variables) | | `include` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>Predefined project variables are supported: `GITLAB_FEATURES`, `CI_DEFAULT_BRANCH`, and all variables that start with `CI_PROJECT_` (for example `CI_PROJECT_NAME`). | | `variables` | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | | `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -63,11 +63,11 @@ because the expansion is done in GitLab before any runner gets the job. #### Nested variable expansion -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It can be enabled or disabled for a single project. -> - It's disabled on GitLab.com. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-nested-variable-expansion-feature). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10. [Deployed behind the `variable_inside_variable` feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/297382) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is disabled. To enable the feature per project or for your entire instance, ask an administrator to [enable the `variable_inside_variable` flag](../../administration/feature_flags.md). GitLab expands job variable values recursively before sending them to the runner. For example: @@ -86,29 +86,6 @@ References to unavailable variables are left intact. In this case, the runner [attempts to expand the variable value](#gitlab-runner-internal-variable-expansion-mechanism) at runtime. For example, a variable like `CI_BUILDS_DIR` is known by the runner only at runtime. -##### Enabling the nested variable expansion feature **(FREE SELF)** - -This feature comes with the `:variable_inside_variable` feature flag disabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -# For the instance -Feature.enable(:variable_inside_variable) -# For a single project -Feature.enable(:variable_inside_variable, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:variable_inside_variable) -# For a single project -Feature.disable(:variable_inside_variable, Project.find(<project id>)) -``` - ### GitLab Runner internal variable expansion mechanism - Supported: project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index 6cd900123e0..ea05aa45b0b 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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/#designated-technical-writers type: reference --- diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 673a4e75c35..92bf44cca7f 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,76 +1,81 @@ --- stage: Verify -group: Pipeline Execution +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 --- # GitLab CI/CD include examples **(FREE)** -In addition to the [`includes` examples](index.md#include) listed in the -[GitLab CI YAML reference](index.md), this page lists more variations of `include` -usage. +You can use [`include`](index.md#include) to include external YAML files in your CI/CD jobs. -## Single string or array of multiple values +## Include a single configuration file -You can include your extra YAML file(s) either as a single string or -an array of multiple values. The following examples are all valid. +To include a single configuration file, use either of these syntax options: -Single string with the `include:local` method implied: +- `include` by itself with a single file, which is the same as + [`include:local`](index.md#includelocal): -```yaml -include: '/templates/.after-script-template.yml' -``` + ```yaml + include: '/templates/.after-script-template.yml' + ``` -Array with `include` method implied: +- `include` with a single file, and you specify the `include` type: -```yaml -include: - - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - '/templates/.after-script-template.yml' -``` + ```yaml + include: + remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + ``` -Single string with `include` method specified explicitly: +## Include an array of configuration files -```yaml -include: - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' -``` +You can include an array of configuration files: -Array with `include:remote` being the single item: +- If you do not specify an `include` type, the type defaults to [`include:local`](index.md#includelocal): -```yaml -include: - - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' -``` + ```yaml + include: + - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - '/templates/.after-script-template.yml' + ``` -Array with multiple `include` methods specified explicitly: +- You can define a single item array: -```yaml -include: - - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - local: '/templates/.after-script-template.yml' - - template: Auto-DevOps.gitlab-ci.yml -``` + ```yaml + include: + - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + ``` -Array mixed syntax: +- You can define an array and explicitly specify multiple `include` types: -```yaml -include: - - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - '/templates/.after-script-template.yml' - - template: Auto-DevOps.gitlab-ci.yml - - project: 'my-group/my-project' - ref: main - file: '/templates/.gitlab-ci-template.yml' -``` + ```yaml + include: + - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - local: '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + ``` + +- You can define an array that combines both default and specific `include` type: + + ```yaml + include: + - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + - project: 'my-group/my-project' + ref: main + file: '/templates/.gitlab-ci-template.yml' + ``` -## Re-using a `before_script` template +## Use `default` configuration from an included configuration file -In the following example, the content of `.before-script-template.yml` is -automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. +You can define a [`default`](index.md#custom-default-keyword-values) section in a +configuration file. When you use a `default` section with the `include` keyword, the defaults apply to +all jobs in the pipeline. -Content of `https://gitlab.com/awesome-project/raw/main/.before-script-template.yml`: +For example, you can use a `default` section with [`before_script`](index.md#before_script). + +Content of a custom configuration file named `/templates/.before-script-template.yml`: ```yaml default: @@ -83,19 +88,29 @@ default: Content of `.gitlab-ci.yml`: ```yaml -include: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' +include: '/templates/.before-script-template.yml' -rspec: +rspec1: + script: + - bundle exec rspec + +rspec2: script: - bundle exec rspec ``` -## Overriding external template values +The default `before_script` commands execute in both `rspec` jobs, before the `script` commands. + +## Override included configuration values -The following example shows specific YAML-defined variables and details of the -`production` job from an include file being customized in `.gitlab-ci.yml`. +When you use the `include` keyword, you can override the included configuration values to adapt them +to your pipeline requirements. -Content of `https://company.com/autodevops-template.yml`: +The following example shows an `include` file that is customized in the +`.gitlab-ci.yml` file. Specific YAML-defined variables and details of the +`production` job are overridden. + +Content of a custom configuration file named `autodevops-template.yml`: ```yaml variables: @@ -136,17 +151,18 @@ production: url: https://domain.com ``` -In this case, the variables `POSTGRES_USER` and `POSTGRES_PASSWORD` along -with the environment URL of the `production` job defined in -`autodevops-template.yml` have been overridden by new values defined in -`.gitlab-ci.yml`. +The `POSTGRES_USER` and `POSTGRES_PASSWORD` variables +and the `environment:url` of the `production` job defined in the `.gitlab-ci.yml` file +override the values defined in the `autodevops-template.yml` file. The other keywords +do not change. This method is called *merging*. + +## Override included configuration arrays -The merging lets you extend and override dictionary mappings, but -you cannot add or modify items to an included array. For example, to add -an additional item to the production job script, you must repeat the -existing script items: +You can use merging to extend and override configuration in an included template, but +you cannot add or modify individual items in an array. For example, to add +an additional `notify_owner` command to the extended `production` job's `script` array: -Content of `https://company.com/autodevops-template.yml`: +Content of `autodevops-template.yml`: ```yaml production: @@ -159,7 +175,7 @@ production: Content of `.gitlab-ci.yml`: ```yaml -include: 'https://company.com/autodevops-template.yml' +include: 'autodevops-template.yml' stages: - production @@ -171,51 +187,32 @@ production: - notify_owner ``` -In this case, if `install_dependencies` and `deploy` were not repeated in -`.gitlab-ci.yml`, they would not be part of the script for the `production` -job in the combined CI configuration. +If `install_dependencies` and `deploy` are not repeated in +the `.gitlab-ci.yml` file, the `production` job would have only `notify_owner` in the script. -## Using nested includes +## Use nested includes -The examples below show how includes can be nested from different sources -using a combination of different methods. +You can nest `include` sections in configuration files that are then included +in another configuration. For example, for `include` keywords nested three deep: -In this example, `.gitlab-ci.yml` includes local the file `/.gitlab-ci/another-config.yml`: +Content of `.gitlab-ci.yml`: ```yaml include: - local: /.gitlab-ci/another-config.yml ``` -The `/.gitlab-ci/another-config.yml` includes a template and the `/templates/docker-workflow.yml` file -from another project: +Content of `/.gitlab-ci/another-config.yml`: ```yaml include: - - template: Bash.gitlab-ci.yml - - project: group/my-project - file: /templates/docker-workflow.yml + - local: /.gitlab-ci/config-defaults.yml ``` -The `/templates/docker-workflow.yml` present in `group/my-project` includes two local files -of the `group/my-project`: +Content of `/.gitlab-ci/config-defaults.yml`: ```yaml -include: - - local: /templates/docker-build.yml - - local: /templates/docker-testing.yml -``` - -Our `/templates/docker-build.yml` present in `group/my-project` adds a `docker-build` job: - -```yaml -docker-build: - script: docker build -t my-image . -``` - -Our second `/templates/docker-test.yml` present in `group/my-project` adds a `docker-test` job: - -```yaml -docker-test: - script: docker run my-image /run/tests.sh +default: + after_script: + - echo "Job complete." ``` diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 63f626e524e..fb5748788f7 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1,15 +1,11 @@ --- stage: Verify -group: Pipeline Execution +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 --- -<!-- markdownlint-disable MD044 --> -<!-- vale gitlab.Spelling = NO --> -# Keyword reference for the .gitlab-ci.yml file **(FREE)** -<!-- vale gitlab.Spelling = YES --> -<!-- markdownlint-enable MD044 --> +# Keyword reference for the `.gitlab-ci.yml` file **(FREE)** This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. @@ -331,7 +327,7 @@ include: #### Switch between branch pipelines and merge request pipelines -> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) GitLab 13.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) in GitLab 13.8. To make the pipeline switch from branch pipelines to merge request pipelines after a merge request is created, add a `workflow: rules` section to your `.gitlab-ci.yml` file. @@ -386,7 +382,7 @@ does not block triggered pipelines. > [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4. Use `include` to include external YAML files in your CI/CD configuration. -You can break down one long `gitlab-ci.yml` file into multiple files to increase readability, +You can break down one long `.gitlab-ci.yml` file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places. You can also store template files in a central repository and `include` them in projects. @@ -434,7 +430,7 @@ In `include` sections in your `.gitlab-ci.yml` file, you can use: - [Project variables](../variables/index.md#add-a-cicd-variable-to-a-project) - [Group variables](../variables/index.md#add-a-cicd-variable-to-a-group) - [Instance variables](../variables/index.md#add-a-cicd-variable-to-an-instance) -- Project [predefined variables](../variables/predefined_variables.md). +- Project [predefined variables](../variables/predefined_variables.md). ```yaml include: @@ -450,12 +446,12 @@ that proposes expanding this feature to support more variables. #### `rules` with `include` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3 and is ready for production use. +> - [Enabled with `ci_include_rules` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) for self-managed GitLab in GitLab 14.3 and is ready for production use. -NOTE: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the `ci_include_rules` flag](../../administration/feature_flags.md). -On GitLab.com, this feature is not available. The feature is not ready for production use. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the `ci_include_rules` flag](../../administration/feature_flags.md). On GitLab.com, this feature is available. You can use [`rules`](#rules) with `include` to conditionally include other configuration files. You can only use `rules:if` in `include` with [certain variables](#variables-with-include). @@ -626,7 +622,7 @@ Use nested includes to compose a set of includes. You can have up to 100 includes, but you can't have duplicate includes. -In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit +In [GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/28212), the time limit to resolve all files is 30 seconds. #### Additional `includes` examples @@ -1141,6 +1137,9 @@ The job is not added to the pipeline: - If no rules match. - If a rule matches and has `when: never`. +You can use [`!reference` tags](#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs) +in different jobs. + #### `rules:if` Use `rules:if` clauses to specify when to add a job to a pipeline: @@ -1368,7 +1367,7 @@ pipeline based on branch names or pipeline types. | `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | | `tags` | When the Git reference for a pipeline is a tag. | - | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). | + | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | **Example of `only:refs` and `except:refs`**: @@ -1591,27 +1590,23 @@ production: #### Requirements and limitations -- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you - can refer to jobs in the same stage as the job you are configuring. This feature is - enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) - this feature is available by default. To hide the feature, ask an administrator to - [disable the `ci_same_stage_job_needs` flag](../../administration/feature_flags.md). -- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. -- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to - a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. - The maximum number of jobs that a single job can need in the `needs:` array is limited: - For GitLab.com, the limit is 50. For more information, see our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit). + - For self-managed instances, the default limit is 50. This limit [can be changed](#changing-the-needs-job-limit). - If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword, it depends on all jobs created in parallel, not just one job. It also downloads artifacts from all the parallel jobs by default. If the artifacts have the same name, they overwrite each other and only the last one downloaded is saved. -- `needs:` is similar to `dependencies:` in that it must use jobs from prior stages, - meaning it's impossible to create circular dependencies. Depending on jobs in the - current stage is not possible either, but [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). -- Stages must be explicitly defined for all jobs - that have the keyword `needs:` or are referred to by one. +- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you + can refer to jobs in the same stage as the job you are configuring. This feature is + enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) + this feature is available by default. +- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be + explicitly defined for all jobs that use the `needs:` keyword, or are referenced + in a job's `needs:` section. +- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to + a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. ##### Changing the `needs:` job limit **(FREE SELF)** @@ -1628,7 +1623,7 @@ To disable directed acyclic graphs (DAG), set the limit to `0`. #### Artifact downloads with `needs` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6. When a job uses `needs`, it no longer downloads all artifacts from previous stages by default, because jobs with `needs` can start before earlier stages complete. With @@ -1680,7 +1675,7 @@ with `needs`. #### Cross project artifact downloads with `needs` **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7. Use `needs` to download artifacts from up to five jobs in pipelines: @@ -1753,7 +1748,7 @@ pipelines running on the same ref could override the artifacts. #### Artifact downloads to child pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab v13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7. A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy. @@ -1832,14 +1827,25 @@ rspec: ### `tags` +> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3. +> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3. + Use `tags` to select a specific runner from the list of all runners that are available for the project. When you register a runner, you can specify the runner's tags, for -example `ruby`, `postgres`, `development`. +example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must +be assigned every tag listed in the job. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). + +**Possible inputs**: -In the following example, the job is run by a runner that -has both `ruby` and `postgres` tags defined. +- An array of tag names. +- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later. + +**Example of `tags`**: ```yaml job: @@ -1848,75 +1854,56 @@ job: - postgres ``` -You can use tags to run different jobs on different platforms. For -example, if you have an OS X runner with tag `osx` and a Windows runner with tag -`windows`, you can run a job on each platform: +In this example, only runners with *both* the `ruby` and `postgres` tags can run the job. -```yaml -windows job: - stage: - - build - tags: - - windows - script: - - echo Hello, %USERNAME%! +**Additional details**: -osx job: - stage: - - build - tags: - - osx - script: - - echo "Hello, $USER!" -``` +- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later, + the number of tags must be less than `50`. -In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35742), you can -use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: +**Related topics**: -```yaml -variables: - KUBERNETES_RUNNER: kubernetes - - job: - tags: - - docker - - $KUBERNETES_RUNNER - script: - - echo "Hello runner selector feature" -``` +- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). ### `allow_failure` -Use `allow_failure` when you want to let a job fail without impacting the rest of the CI -suite. The default value is `false`, except for [manual](../jobs/job_control.md#create-a-job-that-must-be-run-manually) jobs that use -the [`when: manual`](#when) syntax. +Use `allow_failure` to determine whether a pipeline should continue running when a job fails. + +- To let the pipeline continue running subsequent jobs, use `allow_failure: true`. +- To stop the pipeline from running subsequent jobs, use `allow_failure: false`. -In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`, -*including* `when: manual` jobs. +When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**) +indicates that a job failed. However, the pipeline is successful and the associated commit +is marked as passed with no warnings. -When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI. -However, the logical flow of the pipeline considers the job a -success/passed, and is not blocked. +This same warning is displayed when: -Assuming all other jobs are successful, the job's stage and its pipeline -show the same orange warning. However, the associated commit is marked as -"passed", without warnings. +- All other jobs in the stage are successful. +- All other jobs in the pipeline are successful. -In the following example, `job1` and `job2` run in parallel. If `job1` -fails, it doesn't stop the next stage from running, because it's marked with -`allow_failure: true`: +The default value for `allow_failure` is: + +- `true` for [manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually). +- `false` for manual jobs that also use [`rules`](#rules). +- `false` in all other cases. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: `true` or `false`. + +**Example of `allow_failure`**: ```yaml job1: stage: test script: - - execute_script_that_will_fail - allow_failure: true + - execute_script_1 job2: stage: test script: - - execute_script_that_will_succeed + - execute_script_2 + allow_failure: true job3: stage: deploy @@ -1924,14 +1911,35 @@ job3: - deploy_to_staging ``` +In this example, `job1` and `job2` run in parallel: + +- If `job1` fails, jobs in the `deploy` stage do not start. +- If `job2` fails, jobs in the `deploy` stage can still start. + +**Additional details**: + +- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure). +- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs). + A blocked pipeline does not run any jobs in later stages until the manual job + is started and completes successfully. + #### `allow_failure:exit_codes` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9. -Use `allow_failure:exit_codes` to dynamically control if a job should be allowed -to fail. You can list which exit codes are not considered failures. The job fails -for any other exit code: +Use `allow_failure:exit_codes` to control when a job should be +allowed to fail. The job is `allow_failure: true` for any of the listed exit codes, +and `allow_failure` false for any other exit code. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- A single exit code. +- An array of exit codes. + +**Example of `allow_failure`**: ```yaml test_job_1: @@ -2017,7 +2025,7 @@ In this example, the script: **Additional details**: -- In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. - The default behavior of `allow_failure` changes to `true` with `when: manual`. @@ -2136,7 +2144,7 @@ review_app: stage: deploy script: make deploy-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review_app @@ -2147,7 +2155,7 @@ stop_review_app: script: make delete-app when: manual environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop ``` @@ -2197,7 +2205,7 @@ For example, review_app: script: deploy-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG auto_stop_in: 1 day ``` @@ -2267,12 +2275,12 @@ deploy as review app: stage: deploy script: make deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` The `deploy as review app` job is marked as a deployment to dynamically -create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME` +create the `review/$CI_COMMIT_REF_SLUG` environment. `$CI_COMMIT_REF_SLUG` is a [CI/CD variable](../variables/index.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable for inclusion in URLs. If the `deploy as review app` job runs in a branch named @@ -2301,7 +2309,7 @@ Use the `cache:paths` keyword to choose which files or directories to cache. You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns: -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +- In [GitLab Runner 13.0 and later](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). - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). @@ -2377,7 +2385,7 @@ cache-job: ##### `cache:key:files` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. Use the `cache:key:files` keyword to generate a new key when one or two specific files change. `cache:key:files` lets you reuse some caches, and rebuild them less often, @@ -2415,7 +2423,7 @@ fallback key is `default`. ##### `cache:key:prefix` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles). @@ -2864,7 +2872,7 @@ Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't direct link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +- In [GitLab Runner 13.0 and later](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). - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). @@ -3120,7 +3128,7 @@ dashboards. ##### `artifacts:reports:load_performance` **(PREMIUM)** -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. > - Requires GitLab Runner 11.5 and above. The `load_performance` report collects [Load Performance Testing metrics](../../user/project/merge_requests/load_performance_testing.md) @@ -3163,7 +3171,7 @@ marked as Satisfied. ##### `artifacts:reports:sast` > - Introduced in GitLab 11.5. -> - Made [available in all tiers](https://gitlab.com/groups/gitlab-org/-/epics/2098) in GitLab 13.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. > - Requires GitLab Runner 11.5 and above. The `sast` report collects [SAST vulnerabilities](../../user/application_security/sast/index.md) @@ -3176,8 +3184,7 @@ dashboards. ##### `artifacts:reports:secret_detection` > - Introduced in GitLab 13.1. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in GitLab - 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) to GitLab Free in 13.3. > - Requires GitLab Runner 11.5 and above. The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md) @@ -3192,10 +3199,10 @@ dashboards. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. > - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. -The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform +The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/iac/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform plan report uploads to GitLab as an artifact and displays in merge requests. For more information, see -[Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md). +[Output `terraform plan` information into a merge request](../../user/infrastructure/iac/mr_integration.md). #### `artifacts:untracked` @@ -3404,7 +3411,22 @@ You can specify the number of [retry attempts for certain stages of job executio > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3. -Use `timeout` to configure a timeout for a specific job. For example: +Use `timeout` to configure a timeout for a specific job. If the job runs for longer +than the timeout, the job fails. + +The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). + +**Possible inputs**: A period of time written in natural language. For example, these are all equivalent: + +- `3600 seconds` +- `60 minutes` +- `one hour` + +**Example of `timeout`**: ```yaml build: @@ -3416,10 +3438,6 @@ test: timeout: 3h 30m ``` -The job-level timeout can exceed the -[project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) but can't -exceed the runner-specific timeout. - ### `parallel` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. @@ -3583,7 +3601,7 @@ deploystacks: ### `trigger` -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. Use `trigger` to define a downstream pipeline trigger. When GitLab starts a `trigger` job, @@ -3598,11 +3616,11 @@ You can use this keyword to create two different types of downstream pipelines: - [Multi-project pipelines](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file) - [Child pipelines](../pipelines/parent_child_pipelines.md) -[In GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) and later, you can +In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can view which job triggered a downstream pipeline. In the [pipeline graph](../pipelines/index.md#visualize-pipelines), hover over the downstream pipeline job. -In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086). @@ -3756,25 +3774,19 @@ The trigger token is different than the [`trigger`](#trigger) keyword. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -Use `interruptible` to indicate that a running job should be canceled if made redundant by a newer pipeline run. -Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible -and safe to be cancelled. -This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-redundant-pipelines) -is enabled. - -When enabled, a pipeline is immediately canceled when a new pipeline starts on the same branch if either of the following is true: +Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. -- All jobs in the pipeline are set as interruptible. -- Any uninterruptible jobs have not started yet. +This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +feature. When enabled, a running job with `interruptible: true` can be cancelled when +a new pipeline starts on the same branch. -Set jobs as interruptible that can be safely canceled once started (for instance, a build job). +You can't cancel subsequent jobs after a job with `interruptible: false` starts. -In the following example, a new pipeline run causes an existing running pipeline to be: +**Keyword type**: Job keyword. You can use it only as part of a job. -- Canceled, if only `step-1` is running or pending. -- Not canceled, once `step-2` starts running. +**Possible inputs**: `true` or `false` (default). -After an uninterruptible job starts running, the pipeline cannot be canceled. +**Example of `interruptible`**: ```yaml stages: @@ -3800,15 +3812,27 @@ step-3: interruptible: true ``` +In this example, a new pipeline causes a running pipeline to be: + +- Canceled, if only `step-1` is running or pending. +- Not canceled, after `step-2` starts. + +**Additional details**: + +- Only set `interruptible: true` if the job can be safely canceled after it has started, + like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. +- To completely cancel a running pipeline, all jobs must have `interruptible: true`, + or `interruptible: false` jobs must not have started. + ### `resource_group` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. -Sometimes running multiple jobs or pipelines at the same time in an environment +Sometimes running multiple jobs at the same time in an environment can lead to errors during the deployment. To avoid these errors, use the `resource_group` attribute to make sure that -the runner doesn't run certain jobs simultaneously. Resource groups behave similar +the runner doesn't run certain jobs concurrently. Resource groups behave similar to semaphores in other programming languages. When the `resource_group` keyword is defined for a job in the `.gitlab-ci.yml` file, @@ -4333,15 +4357,12 @@ name level and not in the `vault` section. ### `pages` -Use `pages` to upload static content to GitLab. The content -is then published as a website. You must: +Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that +uploads static content to GitLab. The content is then published as a website. -- Place any static content in a `public/` directory. -- Define [`artifacts`](#artifacts) with a path to the `public/` directory. +**Keyword type**: Job name. -The following example moves all files from the root of the project to the -`public/` directory. The `.public` workaround is so `cp` does not also copy -`public/` to itself in an infinite loop: +**Example of `pages`**: ```yaml pages: @@ -4357,7 +4378,15 @@ pages: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` -View the [GitLab Pages user documentation](../../user/project/pages/index.md). +This example moves all files from the root of the project to the `public/` directory. +The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop. + +**Additional details**: + +You must: + +- Place any static content in a `public/` directory. +- Define [`artifacts`](#artifacts) with a path to the `public/` directory. ### `inherit` @@ -4481,7 +4510,7 @@ deploy_review_job: You can use only integers and strings for the variable's name and value. -If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, +If you define a variable at the top level of the `.gitlab-ci.yml` file, it is global, meaning it applies to all jobs. If you define a variable in a job, it's available to that job only. @@ -4495,7 +4524,7 @@ You can use [YAML anchors for variables](#yaml-anchors-for-variables). ### Prefill variables in manual pipelines -> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. Use the `value` and `description` keywords to define [pipeline-level (global) variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually): @@ -4763,6 +4792,7 @@ into templates. ### `!reference` tags > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9. +> - `rules` keyword support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3. Use the `!reference` custom YAML tag to select keyword configuration from other job sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 93c1a6afe69..626ede21fa5 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +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 --- |
