diff options
Diffstat (limited to 'doc/ci')
103 files changed, 671 insertions, 532 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index d34f44ea9ba..c93d2b6a82a 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Caching in GitLab CI/CD **(FREE)** diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index 21b970536bc..3354c94aff2 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: index, concepts, howto --- diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index cfe7be064fb..6256f11f1ea 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index a48822fc214..18cc430c225 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 7c0889a329a..7b9145050bf 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: index, howto --- diff --git a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md index 2d1c3f927e2..4a6b96736df 100644 --- a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md +++ b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to Amazon Elastic Container Service **(FREE)** diff --git a/doc/ci/cloud_deployment/ecs/quick_start_guide.md b/doc/ci/cloud_deployment/ecs/quick_start_guide.md deleted file mode 100644 index 7522bc80d0d..00000000000 --- a/doc/ci/cloud_deployment/ecs/quick_start_guide.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'deploy_to_aws_ecs.md' -remove_date: '2022-09-18' ---- - -This document was moved to [another location](deploy_to_aws_ecs.md). - -<!-- This redirect file can be deleted after <2022-09-18>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/ci/cloud_deployment/heroku.md b/doc/ci/cloud_deployment/heroku.md index 4e627675b01..541ba89dca8 100644 --- a/doc/ci/cloud_deployment/heroku.md +++ b/doc/ci/cloud_deployment/heroku.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab CI/CD to deploy to Heroku diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 82d914f0a6a..83774f63566 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- @@ -11,7 +11,7 @@ GitLab provides Docker images with the libraries and tools you need to deploy to AWS. You can reference these images in your CI/CD pipeline. If you're using GitLab.com and deploying to the [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (ECS), -read about [deploying to ECS](ecs/quick_start_guide.md). +read about [deploying to ECS](ecs/deploy_to_aws_ecs.md). ## Authenticate GitLab with AWS diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md index 2e1abf83a11..cc4dd53b29f 100644 --- a/doc/ci/cloud_services/aws/index.md +++ b/doc/ci/cloud_services/aws/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in AWS to retrieve temporary credentials diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md index 901b36afde6..944f95c03e2 100644 --- a/doc/ci/cloud_services/azure/index.md +++ b/doc/ci/cloud_services/azure/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in Azure to retrieve temporary credentials @@ -16,7 +16,7 @@ Prerequisites: - Access to an existing Azure Subscription with `Owner` access level. - Access to the corresponding Azure Active Directory Tenant with at least the `Application Developer` access level. -- A local installation of the [Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli). +- A local installation of the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli). Alternatively, you can follow all the steps below with the [Azure Cloud Shell](https://shell.azure.com/). - A GitLab project. @@ -27,11 +27,11 @@ To complete this tutorial: 1. [Grant permissions for the service principal](#grant-permissions-for-the-service-principal). 1. [Retrieve a temporary credential](#retrieve-a-temporary-credential). -For more information, review Azure's documentation on [Workload identity federation](https://docs.microsoft.com/azure/active-directory/develop/workload-identity-federation). +For more information, review Azure's documentation on [Workload identity federation](https://learn.microsoft.com/azure/active-directory/develop/workload-identity-federation). ## Create Azure AD application and service principal -To create an [Azure AD application](https://docs.microsoft.com/cli/azure/ad/app?view=azure-cli-latest#az-ad-app-create) +To create an [Azure AD application](https://learn.microsoft.com/cli/azure/ad/app?view=azure-cli-latest#az-ad-app-create) and service principal: 1. In the Azure CLI, create the AD application: @@ -43,13 +43,13 @@ and service principal: Save the `appId` (Application client ID) output, as you need it later to configure your GitLab CI/CD pipeline. -1. Create a corresponding [Service Principal](https://docs.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create): +1. Create a corresponding [Service Principal](https://learn.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create): ```shell az ad sp create --id $appId --query appId -otsv ``` -Instead of the Azure CLI, you can [use the Azure Portal to create these resources](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). +Instead of the Azure CLI, you can [use the Azure Portal to create these resources](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). ## Create Azure AD federated identity credentials @@ -88,7 +88,7 @@ identity credentials from the Azure Portal: ## Grant permissions for the service principal -After you create the credentials, use [`role assignment`](https://docs.microsoft.com/cli/azure/role/assignment?view=azure-cli-latest#az-role-assignment-create) +After you create the credentials, use [`role assignment`](https://learn.microsoft.com/cli/azure/role/assignment?view=azure-cli-latest#az-role-assignment-create) to grant permissions to the above service principal to access to Azure resources: ```shell @@ -97,13 +97,13 @@ az role assignment create --assignee $appId --role Reader --scope /subscriptions You can find your subscription ID in: -- The [Azure Portal](https://docs.microsoft.com/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription). -- The [Azure CLI](https://docs.microsoft.com/cli/azure/manage-azure-subscriptions-azure-cli#get-the-active-subscription). +- The [Azure Portal](https://learn.microsoft.com/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription). +- The [Azure CLI](https://learn.microsoft.com/cli/azure/manage-azure-subscriptions-azure-cli#get-the-active-subscription). ## Retrieve a temporary credential After you configure the Azure AD application and federated identity credentials, -the CI/CD job can retrieve a temporary credential by using the [Azure CLI](https://docs.microsoft.com/cli/azure/reference-index?view=azure-cli-latest#az-login): +the CI/CD job can retrieve a temporary credential by using the [Azure CLI](https://learn.microsoft.com/cli/azure/reference-index?view=azure-cli-latest#az-login): ```yaml default: @@ -123,7 +123,7 @@ The CI/CD variables are: - `AZURE_CLIENT_ID`: The [application client ID you saved earlier](#create-azure-ad-application-and-service-principal). - `AZURE_TENANT_ID`: Your Azure Active Directory. You can - [find it by using the Azure CLI or Azure Portal](https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-how-to-find-tenant). + [find it by using the Azure CLI or Azure Portal](https://learn.microsoft.com/azure/active-directory/fundamentals/active-directory-how-to-find-tenant). - `CI_JOB_JWT_V2`: The JSON web token is a [predefined CI/CD variable](../../variables/predefined_variables.md). ## Troubleshooting diff --git a/doc/ci/cloud_services/google_cloud/index.md b/doc/ci/cloud_services/google_cloud/index.md index 54265816868..ba6efa4d35c 100644 --- a/doc/ci/cloud_services/google_cloud/index.md +++ b/doc/ci/cloud_services/google_cloud/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect with GCP Workload Identity Federation diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index 93fedb0ffca..b7129d92205 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect to cloud services diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index f63ecc57028..ded91edeff5 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 4f6da72af12..e976700c160 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 4c9cb2923d7..06197d71690 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: concepts, howto --- @@ -608,7 +608,7 @@ build: - docker run my-docker-image /script/to/run/tests ``` -To log in to Docker Hub, leave `$DOCKER_REGISTRY` +To sign in to Docker Hub, leave `$DOCKER_REGISTRY` empty or remove it. ### Option 2: Mount `~/.docker/config.json` on each job diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index f985b02be33..70680a44ed2 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: concepts, howto --- @@ -282,8 +282,8 @@ Use one of the following methods to determine the value for `DOCKER_AUTH_CONFIG` configuration JSON manually. Open a terminal and execute the following command: ```shell - # The use of "-n" - prevents encoding a newline in the password. - echo -n "my_username:my_password" | base64 + # The use of printf (as opposed to echo) prevents encoding a newline in the password. + printf "my_username:my_password" | openssl base64 -A # Example output to copy bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= @@ -402,7 +402,7 @@ pulling from Docker Hub fails. Docker daemon tries to use the same credentials f > Introduced in GitLab Runner 12.0. As an example, let's assume that you want to use the `<aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest` -image. This image is private and requires you to log in into a private container registry. +image. This image is private and requires you to sign in to a private container registry. To configure access for `<aws_account_id>.dkr.ecr.<region>.amazonaws.com`, follow these steps: diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index ee8d73dd113..37b9ea87d7a 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index bac06972c7b..adb9b5a87d5 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto --- diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index 26461d9827f..5f5ec027827 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Require approvals prior to deploying to a Protected Environment --- @@ -10,9 +10,6 @@ description: Require approvals prior to deploying to a Protected Environment > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 with a flag named `deployment_approvals`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. -WARNING: -This feature is in a [Beta](../../policy/alpha-beta-support.md#beta-features) stage and subject to change without prior notice. - It may be useful to require additional approvals before deploying to certain protected environments (for example, production). This pre-deployment approval requirement is useful to accommodate testing, security, or compliance processes that must happen before each deployment. When a protected environment requires one or more approvals, all deployments to that environment become blocked and wait for the required approvals from the `Allowed to Deploy` list before running. diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 90efc7ba9ef..665aeb23d28 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deployment safety **(FREE)** diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 11e9fe90e25..f662c156f55 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index ee2e708f822..af431a9812e 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index c34a978709b..63641a9b7c3 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference disqus_identifier: 'https://docs.gitlab.com/ee/ci/environments.html' --- @@ -43,6 +43,18 @@ To view a list of environments and deployments: Deployments show up in this list only after a deployment job has created them. +## Search environments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10754) in GitLab 15.5. + +To search environments by name: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Deployments > Environments**. +1. In the search bar, enter your search term. Matching applies from the + beginning of the environment name. For example, `devel` matches the + environment name `development`, but `elop` does not. + ## Types of environments There are two types of environments: diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index e63777dc0e0..0f943679c07 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected environments **(PREMIUM)** @@ -26,7 +26,7 @@ Maintainer role. Prerequisites: -- When granting the **Allowed to deploy** permission to a group or sub-group, the user configuring the protected environment must be a **direct member** of the group or sub-group to be added. Otherwise, the group or sub-group will not show up in the dropdown. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). +- When granting the **Allowed to deploy** permission to a group or subgroup, the user configuring the protected environment must be a **direct member** of the group or subgroup to be added. Otherwise, the group or subgroup will not show up in the dropdown. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). To protect an environment: @@ -133,7 +133,7 @@ they have the following privileges: Users granted access to a protected environment, but not push or merge access to the branch deployed to it, are only granted access to deploy the environment. [Invited groups](../../user/project/members/share_project_with_groups.md#share-a-project-with-a-group-of-users) added -to the project with [Reporter role](../../user/permissions.md#project-members-permissions), appear in the dropdown menu for deployment-only access. +to the project with [Reporter role](../../user/permissions.md#project-members-permissions), appear in the dropdown list for deployment-only access. To add deployment-only access: @@ -146,7 +146,7 @@ To add deployment-only access: Maintainers can: - Update existing protected environments at any time by changing the access in the - **Allowed to Deploy** dropdown menu. + **Allowed to Deploy** dropdown list. - Unprotect a protected environment by clicking the **Unprotect** button for that environment. After an environment is unprotected, all access entries are deleted and must @@ -194,7 +194,7 @@ and are protected at the same time. ### Configure group-level memberships > - Operators are required to have Owner+ role from the original Maintainer+ role and this role change is introduced from GitLab 15.3 [with a flag](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) named `group_level_protected_environment_settings_permission`. Enabled by default. -> - Original behavior where Operators are required to have Maintainer+ role can be achieved by enabling [flag](https://gitlab.com/gitlab-org/gitlab/-/issues/369875) named `override_group_level_protected_environment_settings_permission`. Disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) in GitLab 15.4. To maximize the effectiveness of group-level protected environments, [group-level memberships](../../user/group/index.md) must be correctly @@ -214,8 +214,8 @@ configured: They do *not* have access to the CI/CD configurations in the top-level group, so operators can ensure that the critical configuration won't be accidentally changed by the developers. -- For sub-groups and child projects: - - Regarding [sub-groups](../../user/group/subgroups/index.md), if a higher +- For subgroups and child projects: + - Regarding [subgroups](../../user/group/subgroups/index.md), if a higher group has configured the group-level protected environment, the lower groups cannot override it. - [Project-level protected environments](#protecting-environments) can be @@ -257,14 +257,10 @@ Configure the group-level protected environments by using the [REST API](../../a Protected environments can also be used to require manual approvals before deployments. See [Deployment approvals](deployment_approvals.md) for more information. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Reporter can't run a trigger job that deploys to a protected environment in downstream pipeline -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +A user who has [deployment-only access to protected environments](#deployment-only-access-to-protected-environments) might **not** be able to run a job if it's with a [`trigger`](../yaml/index.md#trigger) keyword. This is because the job is missing the [`environment`](../yaml/index.md#environment) keyword definition to associate the job with the protected environment, therefore the job is recognized as a normal job that uses [regular CI/CD permission model](../../user/permissions.md#gitlab-cicd-permissions). + +Please see [this issue](https://gitlab.com/groups/gitlab-org/-/epics/8483) for more information about supporting `environment` keyword with `trigger` keyword. diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 00025a66936..59e377dbb09 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index aa4055c00ea..f14372757a9 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index b097f1fac76..7a20bfc2e0a 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- @@ -36,7 +36,7 @@ apt-get install ruby-dev ``` The Dpl provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more. -To use it simply define provider and any additional parameters required by the provider. +To use it, define provider and any additional parameters required by the provider. For example if you want to use it to deploy your application to Heroku, you need to specify `heroku` as provider, specify `api_key` and `app`. All possible parameters can be found in the [Heroku API section](https://github.com/travis-ci/dpl#heroku-api). 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 5ff99755242..e9f126b0409 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments author: Vincent Tunru author_gitlab: Vinnl description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.' @@ -86,7 +86,7 @@ steering the browser. In this case, we can use [`browser.url`](http://v4.webdriver.io/api/protocol/url.html) to visit `/page-that-does-not-exist` to hit our 404 page. We can then use [`browser.getUrl`](http://v4.webdriver.io/api/property/getUrl.html) to verify that the current page is indeed at the location we specified. To interact with the page, -we can simply pass CSS selectors to +we can pass CSS selectors to [`browser.element`](http://v4.webdriver.io/api/protocol/element.html) to get access to elements on the page and to interact with them - for example, to click on the link back to the home page. diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 77591ad2ca6..361061d0d75 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 0735029f0be..80e476f2a87 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html' author: Mehran Rasulian author_gitlab: mehranrasulian diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 9b9f87fffbb..2d0c6382dd8 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- @@ -189,7 +189,7 @@ phpenv config-add my_config.ini Since this is a pretty bare installation of the PHP environment, you may need some extensions that are not currently present on the build machine. -To install additional extensions simply execute: +To install additional extensions, execute: ```shell pecl install <extension> @@ -272,5 +272,5 @@ We have set up an [Example PHP Project](https://gitlab.com/gitlab-examples/php) that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/index.md). -Want to hack on it? Simply fork it, commit, and push your changes. Within a few +Want to hack on it? Fork it, commit, and push your changes. Within a few moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index eaa7d8ebcfa..88e63a7f36f 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Publish npm packages to the GitLab Package Registry using semantic-release **(FREE)** diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index fbecb1cd964..ee9d15894fe 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -60,6 +60,14 @@ To make submodules work correctly in CI/CD jobs: GIT_SUBMODULE_STRATEGY: recursive ``` +1. You can filter or exclude specific submodules to control which submodules will be synced using + [`GIT_SUBMODULE_PATHS`](runners/configure_runners.md#git-submodule-paths). + + ```yaml + variables: + GIT_SUBMODULE_PATHS: submoduleA submoduleB + ``` + 1. You can provide additional flags to control advanced checkout behavior using [`GIT_SUBMODULE_UPDATE_FLAGS`](runners/configure_runners.md#git-submodule-update-flags). diff --git a/doc/ci/index.md b/doc/ci/index.md index be7088ab153..ddc9ba5d475 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset to build, test, and deploy your application." type: index diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 03c905184cf..a1df55cfc38 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index add47c95051..ccf7ebccb2c 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "An overview of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD." type: concepts --- diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 812683ef2c1..7282ebb0909 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD job token **(FREE)** @@ -20,7 +20,8 @@ You can use a GitLab CI/CD job token to authenticate with specific API endpoints (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. +- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter + to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). - [Releases](../../api/releases/index.md) and [Release links](../../api/releases/links.md). - [Terraform plan](../../user/infrastructure/index.md). @@ -78,7 +79,7 @@ to be accessed by authenticating with the current project's job token. By defaul 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 disabled by default for all new projects. It is recommended that project maintainers enable this +This setting is disabled by default for all new projects. It is recommended that project maintainers or owners 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 @@ -99,28 +100,6 @@ The job token scope is only for controlling access to private projects. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve the feature with more strategic control of the access permissions. -## Trigger a multi-project pipeline by using a CI/CD 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](../../api/pipeline_triggers.md#trigger-a-pipeline-with-a-token) -from a CI/CD job. - -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 - environment: production -``` - -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#configure-cicd-jobs-to-run-in-triggered-pipelines). - ## 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. diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index 806837e3dc8..d1a4f1e35bf 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs **(FREE)** diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index 5a94c2e9bbc..39ab0998291 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Choose when to run jobs **(FREE)** @@ -624,8 +624,9 @@ by authorized users. Use [`when: delayed`](../yaml/index.md#when) to execute scripts after a waiting period, or if you want to avoid jobs immediately entering the `pending` state. -You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time in seconds, unless a unit is -provided. `start_in` must be less than or equal to one week. Examples of valid values include: +You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time +in seconds, unless a unit is provided. The minimum is one second, and the maximum is one week. +Examples of valid values include: - `'5'` (a value with no unit must be surrounded by single quotes) - `5 seconds` diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index 3904a527a8f..c7ecc25dc44 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -260,3 +260,8 @@ For very active repositories with a large number of references and files, you ca - Optimize your CI/CD jobs by seeding repository data in a pre-clone step with the [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) of GitLab Runner. See [SaaS runners on Linux](../runners/saas/linux_saas_runner.md#pre-clone-script) for details. + Besides speeding up pipelines in large and active projects, + seeding the repository data also helps avoid + `429 Too many requests` errors from Cloudflare. + This error can occur if you have many runners behind a single, + NAT'ed IP address that pulls from GitLab.com. diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 8c64d968b8b..c297cab1822 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Validate GitLab CI/CD configuration **(FREE)** diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md deleted file mode 100644 index c3ab3392f36..00000000000 --- a/doc/ci/metrics_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'testing/metrics_reports.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](testing/metrics_reports.md). - -<!-- This redirect file can be deleted after <2022-09-22>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index efe11466674..5354e406e34 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index, howto --- diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 35c5a7e56c8..300de610aa7 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index, howto --- @@ -66,6 +66,9 @@ of transition, by letting you delay the migration of less urgent pipelines for a If you are interested in helping GitLab test the wrapper, join our [public testing issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215675) for instructions and to provide your feedback. +NOTE: +If you have a paid GitLab subscription, note that the JenkinsFile Wrapper is not packaged as part of GitLab, and falls outside of the scope of support. For more information, see the [Statement of Support](https://about.gitlab.com/support/statement-of-support.html). + ## Important product differences There are some high level differences between the products worth mentioning: @@ -208,7 +211,7 @@ For advanced CI/CD teams, project templates can enable the reuse of pipeline con as well as encourage inner sourcing. In self-managed GitLab instances, you can build an [Instance Template Repository](../../user/admin_area/settings/instance_template_repository.md). -Development teams across the whole organization can select templates from a dropdown menu. +Development teams across the whole organization can select templates from a dropdown list. A group maintainer or a group owner is able to set a group to use as the source for the [custom project templates](../../user/admin_area/custom_project_templates.md), which can be used by all projects in the group. An instance administrator can set a group as diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md index 6eb56434a1b..1359191f6a6 100644 --- a/doc/ci/mobile_devops.md +++ b/doc/ci/mobile_devops.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 87c2b3f1c71..c4416d41ab4 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index 02a74883244..a5484fcdf5a 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -139,6 +139,8 @@ Premium license: If you use `13,000` minutes during the month, the next month your additional minutes become `2,000`. If you use `9,000` minutes during the month, your additional minutes remain the same. +If you bought additional CI/CD minutes while on a trial subscription those minutes will be available after the trial ends or you upgrade to a paid plan. + You can find pricing for additional CI/CD minutes on the [GitLab Pricing page](https://about.gitlab.com/pricing/). @@ -205,8 +207,8 @@ The cost factors for jobs running on shared runners on GitLab.com are: - `0.5` for public projects in the [GitLab for Open Source program](../../subscriptions/index.md#gitlab-for-open-source). - `0.008` for public forks of public projects in the [GitLab for Open Source program](../../subscriptions/index.md#gitlab-for-open-source). For every 125 minutes of job execution time, you use 1 CI/CD minute. -- `0.04` for other public projects, after September 1, 2022 (previously `0.008`). - For every 25 minutes of job execution time, you use 1 CI/CD minute. +- `1` for other public projects, after October 1, 2022 (previously `0.04`). + For every 1 minute of job execution time, you use 1 CI/CD minute. - Calculated differently for [community contributions to GitLab projects](#cost-factor-for-community-contributions-to-gitlab-projects). The cost factors on self-managed instances are: @@ -246,7 +248,6 @@ GitLab SaaS runners have different cost factors, depending on the runner type (L | Linux OS + Docker executor| Small |1| | Linux OS + Docker executor| Medium |2| | Linux OS + Docker executor| Large |3| -| macOS + shell executor | Large| 6 | ### Monthly reset of CI/CD minutes diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 6c7ec8e98ec..0b1963e1874 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -1,39 +1,65 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Downstream pipelines **(FREE)** A downstream pipeline is any GitLab CI/CD pipeline triggered by another pipeline. -A downstream pipeline can be either: +Downstream pipelines run independently and concurrently to the upstream pipeline +that triggered them. -- A [parent-child pipeline](downstream_pipelines.md#parent-child-pipelines), which is a downstream pipeline triggered - in the same project as the first pipeline. -- A [multi-project pipeline](#multi-project-pipelines), which is a downstream pipeline triggered - in a different project than the first pipeline. +- A [parent-child pipeline](downstream_pipelines.md#parent-child-pipelines) is a downstream pipeline + triggered in the *same* project as the first pipeline. +- A [multi-project pipeline](#multi-project-pipelines) is a downstream pipeline triggered + in a *different* project than the first pipeline. -Parent-child pipelines and multi-project pipelines can sometimes be used for similar purposes, -but there are some key differences. +You can sometimes use parent-child pipelines and multi-project pipelines for similar purposes, +but there are [key differences](pipeline_architectures.md). -Parent-child pipelines: +## Parent-child pipelines + +A parent pipeline is one that triggers a downstream pipeline in the same project. +The downstream pipeline is called a child pipeline. Child pipelines: - Run under the same project, ref, and commit SHA as the parent pipeline. -- Affect the overall status of the ref the pipeline runs against. For example, +- Do not directly affect the overall status of the ref the pipeline runs against. For example, if a pipeline fails for the main branch, it's common to say that "main is broken". - The status of child pipelines don't directly affect the status of the ref, unless the child + The status of child pipelines only affects the status of the ref if the child pipeline is triggered with [`strategy:depend`](../yaml/index.md#triggerstrategy). - Are automatically canceled if the pipeline is configured with [`interruptible`](../yaml/index.md#interruptible) when a new pipeline is created for the same ref. -- Display only the parent pipelines in the pipeline index page. Child pipelines are - visible when visiting their parent pipeline's page. -- Are limited to 2 levels of nesting. A parent pipeline can trigger multiple child pipelines, - and those child pipeline can trigger multiple child pipelines (`A -> B -> C`). +- Are not displayed in the pipeline index page. You can only view child pipelines on + their parent pipeline's page. + +### Nested child pipelines + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243747) in GitLab 13.5. + +Parent and child pipelines were introduced with a maximum depth of one level of child +pipelines, which was later increased to two. A parent pipeline can trigger many child +pipelines, and these child pipelines can trigger their own child pipelines. It's not +possible to trigger another level of child pipelines. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Nested Dynamic Pipelines](https://youtu.be/C5j3ju9je2M). + +## Multi-project pipelines + +A pipeline in one project can trigger downstream pipelines in another project, +called multi-project pipelines. The user triggering the upstream pipeline must be able to +start pipelines in the downstream project, otherwise [the downstream pipeline fails to start](#trigger-job-fails-and-does-not-create-multi-project-pipeline). + +For example, you might deploy your web application from three different GitLab projects. +With multi-project pipelines you can trigger a pipeline in each project, where each +has its own build, test, and deploy process. You can visualize the connected pipelines +in one place, including all cross-project interdependencies. Multi-project pipelines: -- Are triggered from another pipeline, but the upstream (triggering) pipeline does +- Are triggered from another project's pipeline, but the upstream (triggering) pipeline does not have much control over the downstream (triggered) pipeline. However, it can choose the ref of the downstream pipeline, and pass CI/CD variables to it. - Affect the overall status of the ref of the project it runs in, but does not @@ -46,75 +72,86 @@ Multi-project pipelines: that happened to be triggered by an external project. They are all visible on the pipeline index page. - Are independent, so there are no nesting limits. -## Multi-project pipelines +Learn more in the "Cross-project Pipeline Triggering and Visualization" demo at +[GitLab@learn](https://about.gitlab.com/learn/), in the Continuous Integration section. -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. +If you use a public project to trigger downstream pipelines in a private project, +make sure there are no confidentiality problems. The upstream project's pipelines page +always displays: -You can set up [GitLab CI/CD](../index.md) across multiple projects, so that a pipeline -in one project can trigger a downstream pipeline in another project. You can visualize the entire pipeline -in one place, including all cross-project interdependencies. - -For example, you might deploy your web application from three different projects in GitLab. -Each project has its own build, test, and deploy process. With multi-project pipelines you can -visualize the entire pipeline, including all build and test stages for all three projects. +- The name of the downstream project. +- The status of the pipeline. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the [Multi-project pipelines demo](https://www.youtube.com/watch?v=g_PIwBM1J84). +## Trigger a downstream pipeline from a job in the `.gitlab-ci.yml` file -Multi-project pipelines are also useful for larger products that require cross-project interdependencies, like those -with a [microservices architecture](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). -Learn more in the [Cross-project Pipeline Triggering and Visualization demo](https://about.gitlab.com/learn/) -at GitLab@learn, in the Continuous Integration section. +Use the [`trigger`](../yaml/index.md#trigger) keyword in your `.gitlab-ci.yml` file +to create a job that triggers a downstream pipeline. This job is called a trigger job. -If you trigger a pipeline in a downstream private project, on the upstream project's pipelines page, -you can view: +After the trigger job starts, the initial status of the job is `pending` while GitLab +attempts to create the downstream pipeline. If the downstream pipeline is created, +GitLab marks the job as passed, otherwise the job failed. Alternatively, +you can [set the trigger job to show the downstream pipeline's status](#mirror-the-status-of-a-downstream-pipeline-in-the-trigger-job) +instead. -- The name of the project. -- The status of the pipeline. +For example: -If you have a public project that can trigger downstream pipelines in a private project, -make sure there are no confidentiality problems. +::Tabs -### Trigger a multi-project pipeline from a job in your `.gitlab-ci.yml` file +:::TabTitle Multi-project pipeline -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. +```yaml +trigger_job: + trigger: + project: project-group/my-downstream-project +``` -When you use the [`trigger`](../yaml/index.md#trigger) keyword to create a multi-project -pipeline in your `.gitlab-ci.yml` file, you create what is called a *trigger job*. For example: +:::TabTitle Parent-child pipeline ```yaml -rspec: - stage: test - script: bundle exec rspec - -staging: - variables: - ENVIRONMENT: staging - stage: deploy - trigger: my/deployment +trigger_job: + trigger: + include: + - local: path/to/child-pipeline.yml ``` -In this example, after the `rspec` job succeeds in the `test` stage, -the `staging` trigger job starts. The initial status of this -job is `pending`. +::EndTabs -GitLab then creates a downstream pipeline in the -`my/deployment` project and, as soon as the pipeline is created, the -`staging` job succeeds. The full path to the project is `my/deployment`. +### Use `rules` to control downstream pipeline jobs -You can view the status for the pipeline, or you can display -[the downstream pipeline's status instead](#mirror-the-status-of-a-downstream-pipeline-in-the-trigger-job). +You can use CI/CD variables or the [`rules`](../yaml/index.md#rulesif) keyword to +[control job behavior](../jobs/job_control.md) for downstream pipelines. -The user that creates the upstream pipeline must be able to create pipelines in the -downstream project (`my/deployment`) too. If the downstream project is not found, -or the user does not have [permission](../../user/permissions.md) to create a pipeline there, -the `staging` job is marked as _failed_. +When a downstream pipeline is triggered with the [`trigger`](../yaml/index.md#trigger) keyword, +the value of the [`$CI_PIPELINE_SOURCE` predefined variable](../variables/predefined_variables.md) +for all jobs is: -#### Specify a downstream pipeline branch +- `pipeline` for multi-project pipelines. +- `parent` for parent-child pipelines. -You can specify a branch name for the downstream pipeline to use. -GitLab uses the commit on the head of the branch to -create the downstream pipeline. +For example, with a multi-project pipeline: + +```yaml +job1: + rules: + - if: $CI_PIPELINE_SOURCE == "pipeline" + script: echo "This job runs in multi-project pipelines only" + +job2: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: echo "This job runs in merge request pipelines only" + +job3: + rules: + - if: $CI_PIPELINE_SOURCE == "pipeline" + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: echo "This job runs in both multi-project and merge request pipelines" +``` + +### Specify a branch for multi-project pipelines + +You can specify a branch name for a multi-project pipeline to use. GitLab uses +the commit on the head of the branch to create the downstream pipeline: ```yaml rspec: @@ -137,100 +174,25 @@ Use: In [GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/10126), variable expansion is supported. -Pipelines triggered on a protected branch in a downstream project use the [role](../../user/permissions.md) -of the user that ran the trigger job in the upstream project. If the user does not -have permission to run CI/CD pipelines against the protected branch, the pipeline fails. See -[pipeline security for protected branches](index.md#pipeline-security-on-protected-branches). - -#### Use `rules` or `only`/`except` with multi-project pipelines - -You can use CI/CD variables or the [`rules`](../yaml/index.md#rulesif) keyword to -[control job behavior](../jobs/job_control.md) for multi-project pipelines. When a -downstream pipeline is triggered with the [`trigger`](../yaml/index.md#trigger) keyword, -the value of the [`$CI_PIPELINE_SOURCE` predefined variable](../variables/predefined_variables.md) -is `pipeline` for all its jobs. - -If you use [`only/except`](../yaml/index.md#only--except) to control job behavior, use the -[`pipelines`](../yaml/index.md#onlyrefs--exceptrefs) keyword. - -### Trigger a multi-project pipeline by using the API - -> [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](../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. - -These relationships are displayed in the pipeline graph by showing inbound and -outbound connections for upstream and downstream pipeline dependencies. - -When using: - -- CI/CD variables or [`rules`](../yaml/index.md#rulesif) to control job behavior, the value of - the [`$CI_PIPELINE_SOURCE` predefined variable](../variables/predefined_variables.md) is - `pipeline` for multi-project pipeline triggered through the API with `CI_JOB_TOKEN`. -- [`only/except`](../yaml/index.md#only--except) to control job behavior, use the - `pipelines` keyword. - -## Parent-child pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) in GitLab 12.7. - -As pipelines grow more complex, a few related problems start to emerge: - -- The staged structure, where all steps in a stage must be completed before the first - job in next stage begins, causes arbitrary waits, slowing things down. -- Configuration for the single global pipeline becomes very long and complicated, - making it hard to manage. -- Imports with [`include`](../yaml/index.md#include) increase the complexity of the configuration, and create the potential - for namespace collisions where jobs are unintentionally duplicated. -- Pipeline UX can become unwieldy with so many jobs and stages to work with. +### Use a child pipeline configuration file in a different project -Additionally, sometimes the behavior of a pipeline needs to be more dynamic. The ability -to choose to start sub-pipelines (or not) is a powerful ability, especially if the -YAML is dynamically generated. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) in GitLab 13.5. - - -Similarly to [multi-project pipelines](#multi-project-pipelines), a pipeline can trigger a -set of concurrently running downstream child pipelines, but in the same project: - -- Child pipelines still execute each of their jobs according to a stage sequence, but - would be free to continue forward through their stages without waiting for unrelated - jobs in the parent pipeline to finish. -- The configuration is split up into smaller child pipeline configurations. Each child pipeline contains only relevant steps which are - easier to understand. This reduces the cognitive load to understand the overall configuration. -- Imports are done at the child pipeline level, reducing the likelihood of collisions. - -Child pipelines work well with other GitLab CI/CD features: - -- Use [`rules: changes`](../yaml/index.md#ruleschanges) to trigger pipelines only when - certain files change. This is useful for monorepos, for example. -- Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal - pipelines, they can have their own behaviors and sequencing in relation to triggers. - -See the [`trigger`](../yaml/index.md#trigger) keyword documentation for full details on how to -include the child pipeline configuration. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Parent-Child Pipelines feature demo](https://youtu.be/n8KpBSqZNbk). - -NOTE: -The artifact containing the generated YAML file must not be larger than 5MB. - -### Trigger a parent-child pipeline - -The simplest case is [triggering a child pipeline](../yaml/index.md#trigger) using a -local YAML file to define the pipeline configuration. In this case, the parent pipeline -triggers the child pipeline, and continues without waiting: +You can use [`include:file`](../yaml/index.md#includefile) to trigger child pipelines +with a configuration file in a different project: ```yaml microservice_a: trigger: - include: path/to/microservice_a.yml + include: + - project: 'my-group/my-pipeline-library' + ref: 'main' + file: '/path/to/child-pipeline.yml' ``` -You can include multiple files when defining a child pipeline. The child pipeline's +### Combine multiple child pipeline configuration files + +You can include up to three configuration files when defining a child pipeline. The child pipeline's configuration is composed of all configuration files merged together: ```yaml @@ -239,134 +201,139 @@ microservice_a: include: - local: path/to/microservice_a.yml - template: Security/SAST.gitlab-ci.yml -``` - -In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205157), -you can use [`include:file`](../yaml/index.md#includefile) to trigger child pipelines -with a configuration file in a different project: - -```yaml -microservice_a: - trigger: - include: - project: 'my-group/my-pipeline-library' ref: 'main' file: '/path/to/child-pipeline.yml' ``` -The maximum number of entries that are accepted for `trigger:include` is three. +### Dynamic child pipelines -### Merge request child pipelines +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9. -To trigger a child pipeline as a [merge request pipeline](merge_request_pipelines.md) we need to: +You can trigger a child pipeline from a YAML file generated in a job, instead of a +static file saved in your project. This technique can be very powerful for generating pipelines +targeting content that changed or to build a matrix of targets and architectures. -- Set the trigger job to run on merge requests: +The artifact containing the generated YAML file must not be [larger than 5MB](https://gitlab.com/gitlab-org/gitlab/-/issues/249140). -```yaml -# parent .gitlab-ci.yml -microservice_a: - trigger: - include: path/to/microservice_a.yml - rules: - - if: $CI_MERGE_REQUEST_ID -``` +<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). -- Configure the child pipeline by either: +For an example project that generates a dynamic child pipeline, see +[Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet). +This project shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. +You can use a similar process for other templating languages like +[Dhall](https://dhall-lang.org/) or [ytt](https://get-ytt.io/). - - Setting all jobs in the child pipeline to evaluate in the context of a merge request: +#### Trigger a dynamic child pipeline - ```yaml - # child path/to/microservice_a.yml - workflow: - rules: - - if: $CI_MERGE_REQUEST_ID +To trigger a child pipeline from a dynamically generated configuration file: - job1: - script: ... +1. Generate the configuration file in a job and save it as an [artifact](../yaml/index.md#artifactspaths): - job2: - script: ... - ``` + ```yaml + generate-config: + stage: build + script: generate-ci-config > generated-config.yml + artifacts: + paths: + - generated-config.yml + ``` - - Alternatively, setting the rule per job. For example, to create only `job1` in - the context of merge request pipelines: +1. Configure the trigger job to run after the job that generated the configuration file, + and set `include: artifact` to the generated artifact: - ```yaml - # child path/to/microservice_a.yml - job1: - script: ... - rules: - - if: $CI_MERGE_REQUEST_ID + ```yaml + child-pipeline: + stage: test + trigger: + include: + - artifact: generated-config.yml + job: generate-config + ``` - job2: - script: ... - ``` +In this example, `generated-config.yml` is extracted from the artifacts and used as the configuration +for triggering the child pipeline. -### Dynamic child pipelines +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 +runner for testing, the path separator for the trigger job is `/`. Other CI/CD +configuration for jobs that use the Windows runner, like scripts, use `\`. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9. +### Run child pipelines with merge request pipelines -Instead of running a child pipeline from a static YAML file, you can define a job that runs -your own script to generate a YAML file, which is then used to trigger a child pipeline. +To trigger a child pipeline as a [merge request pipeline](merge_request_pipelines.md): -This technique can be very powerful in generating pipelines targeting content that changed or to -build a matrix of targets and architectures. +1. Set the trigger job to run on merge requests: -<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). + ```yaml + # parent .gitlab-ci.yml + microservice_a: + trigger: + include: path/to/microservice_a.yml + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + ``` -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/). +1. Configure the child pipeline jobs to run in merge request pipelines: -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 -runner for testing, the path separator for the trigger job would be `/`. Other CI/CD -configuration for jobs, like scripts, that use the Windows runner would use `\`. + - With [`workflow:rules`](../yaml/index.md#workflowrules): -For example, to trigger a child pipeline from a dynamically generated configuration file: + ```yaml + # child path/to/microservice_a.yml + workflow: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" -```yaml -generate-config: - stage: build - script: generate-ci-config > generated-config.yml - artifacts: - paths: - - generated-config.yml - -child-pipeline: - stage: test - trigger: - include: - - artifact: generated-config.yml - job: generate-config -``` + job1: + script: ... -The `generated-config.yml` is extracted from the artifacts and used as the configuration -for triggering the child pipeline. + job2: + script: ... + ``` -In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail. -This is [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/209070) in GitLab 12.10. + - By configuring [rules](../yaml/index.md#rules) for each job: -### Nested child pipelines + ```yaml + # child path/to/microservice_a.yml + job1: + script: ... + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243747) in GitLab 13.5. + job2: + script: ... + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + ``` -Parent and child pipelines were introduced with a maximum depth of one level of child -pipelines, which was later increased to two. A parent pipeline can trigger many child -pipelines, and these child pipelines can trigger their own child pipelines. It's not -possible to trigger another level of child pipelines. +## Trigger a multi-project pipeline by using the API -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Nested Dynamic Pipelines](https://youtu.be/C5j3ju9je2M). +You can use the [CI/CD job token (`CI_JOB_TOKEN`)](../jobs/ci_job_token.md) with the +[pipeline trigger API endpoint](../../api/pipeline_triggers.md#trigger-a-pipeline-with-a-token) +to trigger multi-project pipelines from a CI/CD job. GitLab recognizes the source of the job token +and marks the pipelines as related. In the pipeline graph, the relationships are displayed +as inbound and outbound connections for upstream and downstream pipeline dependencies. + +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 + environment: production +``` ## View a downstream pipeline +> Hover behavior for pipeline cards [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) in GitLab 13.2. + In the [pipeline graph view](index.md#view-full-pipeline-graph), downstream pipelines display -as a list of cards on the right of the graph. +as a list of cards on the right of the graph. Hover over the pipeline's card to view +which job triggered the downstream pipeline. ### Retry a downstream pipeline @@ -390,9 +357,6 @@ To cancel a downstream pipeline that is still running, select **Cancel** (**{can ### Mirror the status of a downstream pipeline in the trigger job -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11238) in GitLab Premium 12.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. - You can mirror the pipeline status from the triggered pipeline to the source trigger job by using [`strategy: depend`](../yaml/index.md#triggerstrategy): @@ -549,8 +513,9 @@ The `ENVIRONMENT` variable is passed to every job defined in a downstream pipeline. It is available as a variable when GitLab Runner picks a job. In the following configuration, the `MY_VARIABLE` variable is passed to the downstream pipeline -that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream` -job inherits variables declared in global variables blocks, and then we pass these variables to a downstream pipeline. +that is created when the `trigger-downstream` job is queued. This behavior is because `trigger-downstream` +job inherits variables declared in [global `variables`](../yaml/index.md#variables) blocks, +and then GitLab passes these variables to the downstream pipeline. ```yaml variables: @@ -562,7 +527,7 @@ trigger-downstream: trigger: my/project ``` -### Prevent global variables from being passed +#### Prevent global variables from being passed You can stop global variables from reaching the downstream pipeline by using the [`inherit:variables` keyword](../yaml/index.md#inheritvariables). For example, in a [multi-project pipeline](#multi-project-pipelines): @@ -645,3 +610,16 @@ For example, in a [multi-project pipeline](#multi-project-pipelines): ref: master artifacts: true ``` + +## Troubleshooting + +### Trigger job fails and does not create multi-project pipeline + +With multi-project pipelines, the trigger job fails and does not create the downstream pipeline if: + +- The downstream project is not found. +- The user that creates the upstream pipeline does not have [permission](../../user/permissions.md) + to create pipelines in the downstream project. +- The downstream pipeline targets a protected branch and the user does not have permission + to run pipelines against the protected branch. See [pipeline security for protected branches](index.md#pipeline-security-on-protected-branches) + for more information. diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 2696d3adabd..ed0583e0872 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference --- @@ -155,26 +155,38 @@ The pipeline now executes the jobs as configured. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. -You can use the [`value` and `description`](../yaml/index.md#variablesdescription) -keywords to define -[pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) -that are prefilled when running a pipeline manually. +You can use the [`description` and `value`](../yaml/index.md#variablesdescription) +keywords to define [pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +that are prefilled when running a pipeline manually. Use the description to explain +what the variable is used for, what the acceptable values are, and so on. -In pipelines triggered manually, the **Run pipelines** page displays all top-level variables -with a `description` and `value` defined in the `.gitlab-ci.yml` file. The values -can then be modified if needed, which overrides the value for that single pipeline run. +Job-level variables cannot be pre-filled. -The description is displayed next to the variable. It can be used to explain what -the variable is used for, what the acceptable values are, and so on: +In manually-triggered pipelines, the **Run pipeline** page displays all pipeline-level variables +with a `description` defined in the `.gitlab-ci.yml` file. The description displays +below the variable. + +You can change the prefilled value, which overrides the value for that single pipeline run. +If you do not define a `value` for the variable in the configuration file, the variable still displays, +but the value field is blank. + +For example: ```yaml variables: + TEST_SUITE: + description: "The test suite that will run. Valid options are: 'default', 'short', 'full'." + value: "default" DEPLOY_ENVIRONMENT: - value: "staging" # Deploy to staging by default - description: "The deployment target. Change this variable to 'canary' or 'production' if needed." + description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice." ``` -You cannot set job-level variables to be pre-filled when you run a pipeline manually. +In this example: + +- `TEST_SUITE` is pre-filled in the **Run pipeline** page with `default`, + and the message explains the other options. +- `DEPLOY_ENVIRONMENT` is listed in the **Run pipeline** page, but with no value set. + The user is expected to define the value each time the pipeline is run manually. ### Run a pipeline by using a URL query string diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index f30ae32efb2..33a9069240b 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html' --- diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index f6c93356046..714e96d7954 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 88ab6163f3c..c501d2a7904 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge trains **(PREMIUM)** @@ -91,7 +91,7 @@ In GitLab 13.5 and earlier, there is only one checkbox, named **Enable merge trains and pipelines for merged results**. WARNING: -If you select the check box but don't configure your CI/CD to use +If you select the checkbox but don't configure your CI/CD to use merge request pipelines, your merge requests may become stuck in an unresolved state or your pipelines may be dropped. diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index 7209a6b9a77..097f6bad87c 100644 --- a/doc/ci/pipelines/merged_results_pipelines.md +++ b/doc/ci/pipelines/merged_results_pipelines.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merged results pipelines **(PREMIUM)** @@ -33,7 +33,7 @@ To use merged results pipelines: [run jobs in merge request pipelines](merge_request_pipelines.md#prerequisites). - Your repository must be a GitLab repository, not an [external repository](../ci_cd_for_external_repos/index.md). -- You must not be using [fast forward merges](../../user/project/merge_requests/fast_forward_merge.md). +- You must not be using [fast forward merges](../../user/project/merge_requests/methods/index.md). [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/26996) to change this behavior. ## Enable merged results pipelines diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index 824f1445818..25ac9e13185 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -1,11 +1,11 @@ --- redirect_to: 'downstream_pipelines.md' -remove_date: '2022-11-31' +remove_date: '2022-11-30' --- This document was moved to [another location](downstream_pipelines.md). -<!-- This redirect file can be deleted after <2022-11-31>. --> +<!-- This redirect file can be deleted after <2022-11-30>. --> <!-- Redirects that point to other docs in the same project expire in three months. --> <!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index a02ac7ba067..e36eb24055f 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -10,15 +10,21 @@ type: reference Pipelines are the fundamental building blocks for CI/CD in GitLab. This page documents some of the important concepts related to them. -There are three main ways to structure your pipelines, each with their +You can structure your pipelines with different methods, each with their own advantages. These methods can be mixed and matched if needed: - [Basic](#basic-pipelines): Good for straightforward projects where all the configuration is in one easy to find place. - [Directed Acyclic Graph](#directed-acyclic-graph-pipelines): Good for large, complex projects that need efficient execution. -- [Child/Parent Pipelines](#child--parent-pipelines): Good for monorepos and projects with lots of independently defined components. +- [Parent-child pipelines](#parent-child-pipelines): Good for monorepos and projects with lots of independently defined components. -For more details about -any of the keywords used below, check out our [CI YAML reference](../yaml/index.md) for details. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + For an overview, see the [Parent-Child Pipelines feature demo](https://youtu.be/n8KpBSqZNbk). + +- [Multi-project pipelines](downstream_pipelines.md#multi-project-pipelines): Good for larger products that require cross-project interdependencies, + like those with a [microservices architecture](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). + + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + For an overview, see the [Multi-project pipelines demo](https://www.youtube.com/watch?v=g_PIwBM1J84). ## Basic Pipelines @@ -163,12 +169,29 @@ deploy_b: environment: production ``` -## Child / Parent Pipelines +## Parent-child pipelines + +As pipelines grow more complex, a few related problems start to emerge: + +- The staged structure, where all steps in a stage must complete before the first + job in next stage begins, causes waits that slow things down. +- Configuration for the single global pipeline becomes + hard to manage. +- Imports with [`include`](../yaml/index.md#include) increase the complexity of the configuration, and can cause + namespace collisions where jobs are unintentionally duplicated. +- Pipeline UX has too many jobs and stages to work with. + +Additionally, sometimes the behavior of a pipeline needs to be more dynamic. The ability +to choose to start sub-pipelines (or not) is a powerful ability, especially if the +YAML is dynamically generated. + + -In the examples above, it's clear we've got two types of things that could be built independently. -This is an ideal case for using [Child / Parent Pipelines](downstream_pipelines.md#parent-child-pipelines)) via -the [`trigger` keyword](../yaml/index.md#trigger). It separates out the configuration -into multiple files, keeping things very simple. You can also combine this with: +In the [basic pipeline](#basic-pipelines) and [directed acyclic graph](#directed-acyclic-graph-pipelines) +examples above, there are two packages that could be built independently. +These cases are ideal for using [parent-child pipelines](downstream_pipelines.md#parent-child-pipelines). +It separates out the configuration into multiple files, keeping things simpler. +You can combine parent-child pipelines with: - The [`rules` keyword](../yaml/index.md#rules): For example, have the child pipelines triggered only when there are changes to that area. diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md index 07e1c8a6d99..aacaa110041 100644 --- a/doc/ci/pipelines/pipeline_artifacts.md +++ b/doc/ci/pipelines/pipeline_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline artifacts **(FREE)** diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 72711f9b9dd..aa2f074693a 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 897caa340f9..0eeb0eada87 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/schedules.html' type: reference, howto --- @@ -39,6 +39,9 @@ To add a pipeline schedule: These variables are available only when the scheduled pipeline runs, and not in any other pipeline run. +If the project already has the [maximum number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules), +you must delete unused schedules before you can add another. + ## Edit a pipeline schedule > Introduced in GitLab 14.8, only a pipeline schedule owner can edit the schedule. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index d663dea7de8..d7155004359 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/settings.html' type: reference, howto --- @@ -159,13 +159,13 @@ If the CI/CD configuration file is in a different project: - 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. +- The path must be followed by an `@` symbol and the full group and project path. 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` +- `.gitlab-ci.yml@namespace/another-project` +- `my/path/.my-custom-file.yml@namespace/sub-group/another-project` +- `my/path/.my-custom-file.yml@namespace/sub-group1/sub-group2/another-project:refname` If the configuration file is in a separate project, you can set more granular permissions. For example: @@ -329,7 +329,7 @@ you can view a graph or download a CSV file with this data. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Repository**. -The historic data for each job is listed in the dropdown above the graph. +The historic data for each job is listed in the dropdown list above the graph. To view a CSV file of the data, select **Download raw data (`.csv`)**. diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 2b44cf3b898..ad41e4fa88a 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md index dff52a742a8..2803ddba828 100644 --- a/doc/ci/resource_groups/index.md +++ b/doc/ci/resource_groups/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Control the job concurrency in GitLab CI/CD --- diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 9bafb69482b..2f23ebbfd9f 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review Apps **(FREE)** @@ -95,9 +95,14 @@ after a given period of time. The following are example projects that demonstrate Review App configuration: -- [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx). -- [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). -- [HashiCorp Nomad](https://gitlab.com/gitlab-examples/review-apps-nomad). +| Project | Configuration file | +|-------------------------------------------------------------------------|--------------------| +| [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-examples/review-apps-nginx/-/blob/b9c1f6a8a7a0dfd9c8784cbf233c0a7b6a28ff27/.gitlab-ci.yml#L20) | +| [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-examples/review-apps-openshift/-/blob/82ebd572334793deef2d5ddc379f38942f3488be/.gitlab-ci.yml#L42) | +| [HashiCorp Nomad](https://gitlab.com/gitlab-examples/review-apps-nomad) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-examples/review-apps-nomad/-/blob/ca372c778be7aaed5e82d3be24e98c3f10a465af/.gitlab-ci.yml#L110) | +| [GitLab Documentation](https://gitlab.com/gitlab-org/gitlab-docs/) | [`build-and-deploy.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/a715625496303cbd90ff89f3d3658ea8d36ce0f3/.gitlab/ci/build-and-deploy.gitlab-ci.yml#L59) | +| [`https://about.gitlab.com/`](https://gitlab.com/gitlab-com/www-gitlab-com/) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/6ffcdc3cb9af2abed490cbe5b7417df3e83cd76c/.gitlab-ci.yml#L332) | +| [GitLab Insights](https://gitlab.com/gitlab-org/gitlab-insights/) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-insights/-/blob/9e63f44ac2a5a4defc965d0d61d411a768e20546/.gitlab-ci.yml#L234) | Other examples of Review Apps: diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 9d26ec63f96..19e0c1e3c81 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring runners **(FREE)** @@ -198,7 +198,7 @@ To make a runner pick untagged jobs: 1. Select **Save changes** for the changes to take effect. NOTE: -The runner tags list can not be empty when it's not allowed to pick untagged jobs. +The runner tags list cannot be empty when it's not allowed to pick untagged jobs. Below are some example scenarios of different variations. @@ -302,6 +302,7 @@ globally or for individual jobs: - [`GIT_CHECKOUT`](#git-checkout) - [`GIT_CLEAN_FLAGS`](#git-clean-flags) - [`GIT_FETCH_EXTRA_FLAGS`](#git-fetch-extra-flags) +- [`GIT_SUBMODULE_PATHS`](#git-submodule-paths) - [`GIT_SUBMODULE_UPDATE_FLAGS`](#git-submodule-update-flags) - [`GIT_DEPTH`](#shallow-cloning) (shallow cloning) - [`GIT_CLONE_PATH`](#custom-build-directories) (custom build directories) @@ -488,6 +489,32 @@ git fetch origin $REFSPECS --depth 50 --prune Where `$REFSPECS` is a value provided to the runner internally by GitLab. +### Git submodule paths + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/2249) in GitLab Runner 14.0. + +Use the `GIT_SUBMODULE_PATHS` variable to control which submodules have to be synced or updated. +You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. + +This variable can be very useful for projects which have a large number of submodules which not all of them +need to be synced or updated in all CI jobs. + +The path syntax is the same as [`git submodule`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-ltpathgt82308203): + +- To sync and update specific paths: + + ```yaml + variables: + GIT_SUBMODULE_PATHS: submoduleA submoduleB + ``` + +- To exclude specific paths: + + ```yaml + variables: + GIT_SUBMODULE_PATHS: :(exclude)submoduleA :(exclude)submoduleB + ``` + ### Git submodule update flags > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3192) in GitLab Runner 14.8. @@ -915,12 +942,8 @@ To determine which runners need to be upgraded: ## Authentication token security -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to -[enable the feature flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. -On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed. Each runner has an [authentication token](../../api/runners.md#registration-and-authentication-tokens) to connect with the GitLab instance. diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 1de24efa8aa..405310fb8ba 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index f8a33ea6861..4be4ed33feb 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -172,8 +172,12 @@ To create a group runner: 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **CI/CD > Runners**. -1. Note the URL and token. -1. [Register the runner](https://docs.gitlab.com/runner/register/). +1. In the top-right corner, select **Register a group runner**. +1. Select **Show runner installation and registration instructions**. + These instructions include the token, URL, and a command to register a runner. + +Alternately, you can copy the registration token and follow the documentation for +how to [register a runner](https://docs.gitlab.com/runner/register/). ### View and manage group runners @@ -188,6 +192,23 @@ You must have the Owner role for the group. From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects. +#### Filter group runners to show only inherited + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337838/) in GitLab 15.5. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101099) in GitLab 15.5. Feature flag `runners_finder_all_available` removed. + +You can choose to show all runners in the list, or show only +those that are inherited from the instance or other groups. + +By default, only those that are inherited are shown. + +To show all runners available in the instance, including shared runners and +those in other groups: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **CI/CD > Runners**. +1. Above the list, turn off the **Show only inherited** toggle. + ### Pause or remove a group runner You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index a7d1b8722a5..d1c63ab7291 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Linux diff --git a/doc/ci/runners/saas/macos/codesigning.md b/doc/ci/runners/saas/macos/codesigning.md index 71fdc61f0b6..697f138eec6 100644 --- a/doc/ci/runners/saas/macos/codesigning.md +++ b/doc/ci/runners/saas/macos/codesigning.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code signing for SaaS runners on macOS diff --git a/doc/ci/runners/saas/macos/environment.md b/doc/ci/runners/saas/macos/environment.md index edd897e4c23..1fc7afea7e6 100644 --- a/doc/ci/runners/saas/macos/environment.md +++ b/doc/ci/runners/saas/macos/environment.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # VM instances and images for SaaS runners on macOS **(PREMIUM SAAS)** @@ -57,5 +57,6 @@ Each image is running a specific version of macOS and Xcode. | `macos-10.14-xcode-10` | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/mojave.yml> | | `macos-10.15-xcode-11` | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/catalina.yml> | | `macos-11-xcode-12` | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/big-sur.yml> | -| `macos-12-xcode-13` | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> | +| `macos-12-xcode-13` | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> | +| `macos-12-xcode-14` | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> | | (none, awaiting macOS 13) | `beta` | | diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index 5a2d84b6996..50c24349712 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on macOS (Beta) **(PREMIUM SAAS)** @@ -14,10 +14,6 @@ Use these runners to build, test, and deploy apps for the Apple ecosystem (macOS of all the capabilities of the GitLab single DevOps platform and not have to manage or operate a build environment. -CI/CD minutes used on GitLab SaaS macOS runners are included in your CI/CD minute consumption totals. CI jobs that run on macOS **will** consume CI minutes at a faster rate than CI jobs on the GitLab SaaS runners on Linux. - -Refer to the CI/CD minutes [cost factor](../../../ci/pipelines/cicd_minutes.md#cost-factor) for the cost factor applied to the GitLab SaaS macOS runners. - Jobs handled by macOS shared runners on GitLab.com **time out after 2 hours**, regardless of the timeout configured in a project. ## Access request process diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index f9fe6290220..2c6540833b0 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Windows (beta) **(FREE SAAS)** diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index fb91aeb6240..62350905bd4 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: concepts, howto --- @@ -56,7 +56,7 @@ To configure your Vault server: 1. Ensure your Vault server is running on version 1.2.0 or higher. 1. Enable the authentication method by running these commands. They provide your Vault - server the [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) (JWKS) endpoint for your GitLab instance, so Vault + server the [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517) (JWKS) endpoint for your GitLab instance, so Vault can fetch the public signing key and verify the JSON Web Token (JWT) when authenticating: ```shell diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index ff5c29cdb06..bba8a3e4c27 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -13,7 +13,13 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `ci_secure_files`. Limited to 100 secure files per project. Files must be smaller -than 5 MB. The feature is not ready for production use. +than 5 MB. Project-level Secure Files is an experimental feature developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). + +Project-level Secure Files is still in development, but you can: + +- [Request a feature](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=feature_request). +- [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). +- [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). You can securely store files for use in CI/CD pipelines as "secure files". These files are stored securely outside of your project's repository, and are not version controlled. diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 689ce884ae4..f2ea969f430 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index 9b2bcc39b3e..0f82f2301c7 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- @@ -370,8 +370,11 @@ access-service: 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). +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). +- [Not use the Docker executor with Docker socket binding](../docker/using_docker_build.md#use-the-docker-executor-with-docker-socket-binding). + If you must, then in the above example, instead of `host`, use the dynamic network name created for this job. ## How Docker integration works diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index d0ac123ba62..ea11719cef1 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index c2ff4c60771..139a4a2f742 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index a3446fc2677..a7a28116aa4 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -1,7 +1,7 @@ --- stage: Verify 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -69,5 +69,5 @@ We have set up an [Example Redis Project](https://gitlab.com/gitlab-examples/red that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/index.md). -Want to hack on it? Simply fork it, commit and push your changes. Within a few +Want to hack on it? Fork it, commit and push your changes. Within a few moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index 30b688c0b96..972e9494126 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- @@ -10,13 +10,13 @@ type: tutorial GitLab currently doesn't have built-in support for managing SSH keys in a build environment (where the GitLab Runner runs). -Use SSH keys when: +Use SSH keys when you want to: -1. You want to checkout internal submodules -1. You want to download private packages using your package manager (for example, Bundler) -1. You want to deploy your application to your own server, or, for example, Heroku -1. You want to execute SSH commands from the build environment to a remote server -1. You want to rsync files from the build environment to a remote server +- Check out internal submodules. +- Download private packages using your package manager. For example, Bundler. +- Deploy your application to your own server or, for example, Heroku. +- Execute SSH commands from the build environment to a remote server. +- Rsync files from the build environment to a remote server. If anything of the above rings a bell, then you most likely need an SSH key. @@ -115,9 +115,9 @@ SSH key. You can generate the SSH key from the machine that GitLab Runner is installed on, and use that key for all projects that are run on this machine. -1. First, log in to the server that runs your jobs. +1. First, sign in to the server that runs your jobs. -1. Then, from the terminal, log in as the `gitlab-runner` user: +1. Then, from the terminal, sign in as the `gitlab-runner` user: ```shell sudo su - gitlab-runner diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 3ef25a4924b..8d2788539d8 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Test cases in GitLab can help your teams create testing scenarios in their existing development platform. type: reference --- @@ -36,7 +36,10 @@ issue list with a search query, including labels or the test case's title. Prerequisite: -- You must have at least the Guest role. +Whether you can view an test case depends on the [project visibility level](../../user/public_access.md): + +- Public project: You don't have to be a member of the project. +- Private project: You must have at least the Guest role for the project. To view a test case: diff --git a/doc/ci/testing/accessibility_testing.md b/doc/ci/testing/accessibility_testing.md index 7940b27acf7..fa57371a7d5 100644 --- a/doc/ci/testing/accessibility_testing.md +++ b/doc/ci/testing/accessibility_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Accessibility testing **(FREE)** diff --git a/doc/ci/testing/browser_performance_testing.md b/doc/ci/testing/browser_performance_testing.md index 260ecf6108d..ff013f0037e 100644 --- a/doc/ci/testing/browser_performance_testing.md +++ b/doc/ci/testing/browser_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Browser Performance Testing **(PREMIUM)** diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 401279b9601..7345c7ca5eb 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Quality **(FREE)** @@ -313,7 +313,7 @@ the nested architecture of container execution, the registry prefix must be specifically configured to be passed down into CodeClimate's subsequent `docker pull` commands for individual engines. -The following two variables can address all of the required image pulls: +The following variables can address all of the required image pulls: - `CODE_QUALITY_IMAGE`: A fully prefixed image name that can be located anywhere accessible from your job environment. GitLab Container Registry can be used here @@ -322,6 +322,8 @@ The following two variables can address all of the required image pulls: is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). You must: - Include a trailing slash (`/`). - Not include a protocol prefix, such as `https://`. +- `CODECLIMATE_REGISTRY_USERNAME`: An optional variable to specify the username for the registry domain parsed from `CODECLIMATE_PREFIX`. +- `CODECLIMATE_REGISTRY_PASSWORD`: An optional variable to specify the password for the registry domain parsed from `CODECLIMATE_PREFIX`. ```yaml include: @@ -333,13 +335,49 @@ code_quality: CODECLIMATE_PREFIX: "my-private-registry.local:12345/" ``` -The images in the private container image registry must be available without authentication. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/355814) for more information. - This example is specific to GitLab Code Quality. For more general instructions on how to configure DinD with a registry mirror, see the relevant [documentation](../docker/using_docker_build.md#enable-registry-mirror-for-dockerdind-service). +#### Configure Code Quality to use the Dependency Proxy + +Prerequisite: + +- The project must be in a group where the [Dependency Proxy](../../user/packages/dependency_proxy/index.md) is enabled. + +Here is an example of how to configure Code Quality to use the Dependency Proxy: + +```yaml +include: + - template: Jobs/Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODE_QUALITY_IMAGE: "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/codequality:0.85.24" + ## You must add a trailing slash to `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`. + CODECLIMATE_PREFIX: $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/ + CODECLIMATE_REGISTRY_USERNAME: $CI_DEPENDENCY_PROXY_USER + CODECLIMATE_REGISTRY_PASSWORD: $CI_DEPENDENCY_PROXY_PASSWORD +``` + +#### Configure Code Quality to use Dockerhub with authentication + +Here is an example of how to configure Code Quality to use Dockerhub with authentication: + +```yaml +include: + - template: Jobs/Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODECLIMATE_PREFIX: "registry-1.docker.io/" + CODECLIMATE_REGISTRY_USERNAME: $DOCKERHUB_USERNAME + CODECLIMATE_REGISTRY_PASSWORD: $DOCKERHUB_PASSWORD +``` + +You should add the username and password as [protected CI/CD variables](../variables/index.md#add-a-cicd-variable-to-a-project) +in the project. + ## Configuring jobs using variables The Code Quality job supports environment variables that users can set to diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md index 7b95b1ac54a..58471a626da 100644 --- a/doc/ci/testing/fail_fast_testing.md +++ b/doc/ci/testing/fail_fast_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fail Fast Testing **(PREMIUM)** diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md index a8f06ec695c..41d474f0e60 100644 --- a/doc/ci/testing/index.md +++ b/doc/ci/testing/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test with GitLab CI/CD and generate reports in merge requests **(FREE)** diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md index e15b3944c2b..6e1b440f252 100644 --- a/doc/ci/testing/load_performance_testing.md +++ b/doc/ci/testing/load_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Performance Testing **(PREMIUM)** diff --git a/doc/ci/testing/metrics_reports.md b/doc/ci/testing/metrics_reports.md index e855074ddea..e084e4d3bc7 100644 --- a/doc/ci/testing/metrics_reports.md +++ b/doc/ci/testing/metrics_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics Reports **(PREMIUM)** diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 472cfca99be..ee6b47e69a5 100644 --- a/doc/ci/testing/test_coverage_visualization.md +++ b/doc/ci/testing/test_coverage_visualization.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test coverage visualization **(FREE)** diff --git a/doc/ci/testing/unit_test_report_examples.md b/doc/ci/testing/unit_test_report_examples.md index b49ac29be65..c14e4eedd7c 100644 --- a/doc/ci/testing/unit_test_report_examples.md +++ b/doc/ci/testing/unit_test_report_examples.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test report examples **(FREE)** @@ -183,7 +183,11 @@ the `javascript` job uses Jest to generate the test reports: ```yaml javascript: + image: node:latest stage: test + before_script: + - 'yarn global add jest' + - 'yarn add --dev jest-junit' script: - 'jest --ci --reporters=default --reporters=jest-junit' artifacts: @@ -193,6 +197,9 @@ javascript: - junit.xml ``` +To make the job pass when there are no `.test.js` files with unit tests, add the +`--passWithNoTests` flag to the end of the `jest` command in the `script:` section. + ### Karma The [Karma-junit-reporter](https://github.com/karma-runner/karma-junit-reporter) diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index 28356a62c99..0fe9b2b6d64 100644 --- a/doc/ci/testing/unit_test_reports.md +++ b/doc/ci/testing/unit_test_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test reports **(FREE)** diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index 36d136727b0..cafa64c4832 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 8a03ec0b56f..8f78469af18 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md deleted file mode 100644 index 7578a1e6009..00000000000 --- a/doc/ci/unit_test_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'testing/unit_test_reports.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](testing/unit_test_reports.md). - -<!-- This redirect file can be deleted after <2022-08-31>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index 25178903c9a..7ad42aaf96b 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -193,7 +193,7 @@ The output is: > Support for environment scopes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) in GitLab Premium 13.11 -To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. +To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. Only group owners can add or update group-level CI/CD variables. Use group variables to store secrets like passwords, SSH keys, and credentials, if you: @@ -682,7 +682,10 @@ The order of precedence for variables is (from highest to lowest): - [Manual pipeline run variables](#override-a-variable-when-running-a-pipeline-manually). - Variables added when [creating a pipeline with the API](../../api/pipelines.md#create-a-new-pipeline). 1. Project [variables](#custom-cicd-variables). -1. Group [variables](#add-a-cicd-variable-to-a-group). +1. Group [variables](#add-a-cicd-variable-to-a-group). If the same variable name exists in a + group and its subgroups, the job uses the value from the closest subgroup. For example, if + you have `Group > Subgroup 1 > Subgroup 2 > Project`, the variable defined in + `Subgroup 2` takes precedence. 1. Instance [variables](#add-a-cicd-variable-to-an-instance). 1. [Inherited variables](#pass-an-environment-variable-to-another-job). 1. Variables defined in jobs in the `.gitlab-ci.yml` file. @@ -768,7 +771,7 @@ for [deployment jobs](../environments/index.md). For example, the [Kubernetes integration](../../user/project/clusters/deploy_to_cluster.md#deployment-variables) defines deployment variables that you can use with the integration. -The [documentation for each integration](../../user/project/integrations/overview.md) +The [documentation for each integration](../../user/project/integrations/index.md) explains if the integration has any deployment variables available. ## Auto DevOps environment variables diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 77005e1cec4..606847ee756 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -39,6 +39,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_COMMIT_SHA` | 9.0 | all | The commit revision the project is built for. | | `CI_COMMIT_SHORT_SHA` | 11.7 | all | The first eight characters of `CI_COMMIT_SHA`. | | `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Available only in pipelines for tags. | +| `CI_COMMIT_TAG_MESSAGE` | 15.5 | all | The commit tag message. Available only in pipelines for tags. | | `CI_COMMIT_TIMESTAMP` | 13.4 | all | The timestamp of the commit in the ISO 8601 format. | | `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit. The full first line of the message. | | `CI_CONCURRENT_ID` | all | 11.10 | The unique ID of build execution in a single executor. | @@ -60,6 +61,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/index.md#environmenturl) is set. | | `CI_ENVIRONMENT_ACTION` | 13.11 | all | The action annotation specified for this job's environment. Available if [`environment:action`](../yaml/index.md#environmentaction) is set. Can be `start`, `prepare`, or `stop`. | | `CI_ENVIRONMENT_TIER` | 14.0 | all | The [deployment tier of the environment](../environments/index.md#deployment-tier-of-environments) for this job. | +| `CI_RELEASE_DESCRIPTION` | 15.5 | all | The description of the release. Available only on pipelines for tags. Description length is limited to first 1024 characters.| | `CI_GITLAB_FIPS_MODE` | 14.10 | all | The configuration setting for whether FIPS mode is enabled in the GitLab instance. | | `CI_HAS_OPEN_REQUIREMENTS` | 13.1 | all | Only available if the pipeline's project has an open [requirement](../../user/project/requirements/index.md). `true` when available. | | `CI_JOB_ID` | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | @@ -69,11 +71,12 @@ as it can cause the pipeline to behave unexpectedly. | `CI_JOB_JWT_V2` | 14.6 | all | A newly formatted RS256 JSON web token to increase compatibility. Similar to `CI_JOB_JWT`, except the issuer (`iss`) claim is changed from `gitlab.com` to `https://gitlab.com`, `sub` has changed from `job_id` to a string that contains the project path, and an `aud` claim is added. Format is subject to change. Be aware, the `aud` field is a constant value. Trusting JWTs in multiple relying parties can lead to [one RP sending a JWT to another one and acting maliciously as a job](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72555#note_769112331). **Note:** The `CI_JOB_JWT_V2` variable is available for testing, but the full feature is planned to be generally available when [issue 360657](https://gitlab.com/gitlab-org/gitlab/-/issues/360657) is complete.| | `CI_JOB_MANUAL` | 8.12 | all | Only available if the job was started manually. `true` when available. | | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. | +| `CI_JOB_NAME_SLUG` | 15.4 | all | `CI_JOB_NAME_SLUG` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in paths. | | `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](../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_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://www.rfc-editor.org/rfc/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. | | `CI_NODE_INDEX` | 11.5 | all | The index of the job in the job set. Only available if the job uses [`parallel`](../yaml/index.md#parallel). | | `CI_NODE_TOTAL` | 11.5 | all | The total number of instances of this job running in parallel. Set to `1` if the job does not use [`parallel`](../yaml/index.md#parallel). | @@ -85,7 +88,7 @@ as it can cause the pipeline to behave unexpectedly. | `CI_PIPELINE_SOURCE` | 10.0 | all | How the pipeline was triggered. Can be `push`, `web`, `schedule`, `api`, `external`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, [`trigger`, or `pipeline`](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). For a description of each value, see [Common `if` clauses for `rules`](../jobs/job_control.md#common-if-clauses-for-rules), which uses this variable to control when jobs run. | | `CI_PIPELINE_TRIGGERED` | all | all | `true` if the job was [triggered](../triggers/index.md). | | `CI_PIPELINE_URL` | 11.1 | 0.5 | The URL for the pipeline details. | -| `CI_PIPELINE_CREATED_AT` | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://tools.ietf.org/html/rfc3339#appendix-A) format. | +| `CI_PIPELINE_CREATED_AT` | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | | `CI_PROJECT_CONFIG_PATH` | 13.8 to 13.12 | all | [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/322807) in GitLab 14.0. Use `CI_CONFIG_PATH`. | | `CI_PROJECT_DIR` | all | all | The full path the repository is cloned to, and where the job runs from. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see the [Advanced GitLab Runner configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | | `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 6c1737f7c65..7e5451658f2 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index 56a9da7cb84..67cbe989f74 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD artifacts reports types **(FREE)** diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index f3773fbf143..7b4834b3719 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 5158f80ea64..2b9f42e1c75 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 8aa3ebd4759..e06abe1dc69 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -379,7 +379,7 @@ start. Jobs in the current stage are not stopped and continue to run. - If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage. - If a stage is defined but no jobs use it, the stage is not visible in the pipeline, - which can help [compliance pipeline configurations](../../user/project/settings/index.md#compliance-pipeline-configuration): + which can help [compliance pipeline configurations](../../user/group/manage.md#configure-a-compliance-pipeline): - Stages can be defined in the compliance configuration but remain hidden if not used. - The defined stages become visible when developers use them in job definitions. @@ -398,6 +398,30 @@ Use [`workflow`](workflow.md) to control pipeline behavior. - [`workflow: rules` examples](workflow.md#workflow-rules-examples) - [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines) +#### `workflow:name` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372538) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `pipeline_name`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `pipeline_name`. +The feature is not ready for production use. + +You can use `name` in `workflow:` to define a name for pipelines. + +All pipelines are assigned the defined name. Any leading or trailing spaces in the name are removed. + +**Possible inputs**: + +- A string. + +**Example of `workflow:name`**: + +```yaml +workflow: + name: 'Pipeline name' +``` + #### `workflow:rules` The `rules` keyword in `workflow` is similar to [`rules` defined in jobs](#rules), @@ -1238,7 +1262,11 @@ is not found, the prefix is added to `default`, so the key in the example would #### `cache:untracked` -Use `untracked: true` to cache all files that are untracked in your Git repository: +Use `untracked: true` to cache all files that are untracked in your Git repository. +Untracked files include files that are: + +- Ignored due to [`.gitignore` configuration](https://git-scm.com/docs/gitignore). +- Created, but not added to the checkout with [`git add`](https://git-scm.com/docs/git-add). **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -1259,7 +1287,7 @@ rspec: **Additional details**: - You can combine `cache:untracked` with `cache:paths` to cache all untracked files - as well as files in the configured paths. For example: + as well as files in the configured paths. This is useful for including files that are not tracked because of a `.gitignore` configuration. For example: ```yaml rspec: @@ -2161,7 +2189,7 @@ This example creates four paths of execution: 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. + a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. In GitLab 13.10 and later, use the [`needs:optional`](#needsoptional) keyword to resolve a failed pipeline creation. #### `needs:artifacts` @@ -3260,8 +3288,19 @@ branch or merge request pipelines. **Possible inputs**: -- An array of file paths. In GitLab 13.6 and later, [file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). -- Alternatively, the array of file paths can be in [`rules:changes:paths`](#ruleschangespaths). +An array including any number of: + +- Paths to files. In GitLab 13.6 and later, [file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). + A file path array can also be in [`rules:changes:paths`](#ruleschangespaths). +- Wildcard paths for: + - Single directories, for example `path/to/directory/*`. + - A directory and all its subdirectories, for example `path/to/directory/**/*`. +- Wildcard [glob](https://en.wikipedia.org/wiki/Glob_(programming)) paths for all files + with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`. + See the [Ruby `fnmatch` documentation](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + for the supported syntax list. +- Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. + For example `"*.json"` or `"**/*.json"`. **Example of `rules:changes`**: @@ -3332,7 +3371,8 @@ In this example, both jobs have the same behavior. ##### `rules:changes:compare_to` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366412) in GitLab 15.5. Feature flag `ci_rules_changes_compare` removed. Use `rules:changes:compare_to` to specify which ref to compare against for changes to the files listed under [`rules:changes:paths`](#ruleschangespaths). @@ -3938,7 +3978,7 @@ trigger-multi-project-pipeline: **Related topics**: -- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-from-a-job-in-your-gitlab-ciyml-file). +- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file). - To run a pipeline for a specific branch, tag, or commit, you can use a [trigger token](../triggers/index.md) to authenticate with the [pipeline triggers API](../../api/pipeline_triggers.md). The trigger token is different than the `trigger` keyword. @@ -3966,7 +4006,7 @@ trigger-child-pipeline: **Related topics**: -- [Child pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-parent-child-pipeline). +- [Child pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file). #### `trigger:project` @@ -4002,7 +4042,7 @@ trigger-multi-project-pipeline: **Related topics**: -- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-from-a-job-in-your-gitlab-ciyml-file). +- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file). - To run a pipeline for a specific branch, tag, or commit, you can also use a [trigger token](../triggers/index.md) to authenticate with the [pipeline triggers API](../../api/pipeline_triggers.md). The trigger token is different than the `trigger` keyword. @@ -4160,9 +4200,9 @@ deploy_review_job: Use the `description` keyword to define a [pipeline-level (global) variable that is prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually). -Must be used with `value`, for the variable value. +If used with `value`, the variable value is also prefilled when running a pipeline manually. -**Keyword type**: Global keyword. You cannot set job-level variables to be pre-filled when you run a pipeline manually. +**Keyword type**: Global keyword. You cannot use it for job-level variables. **Possible inputs**: @@ -4173,10 +4213,15 @@ Must be used with `value`, for the variable value. ```yaml variables: DEPLOY_ENVIRONMENT: - value: "staging" description: "The deployment target. Change this variable to 'canary' or 'production' if needed." + value: "staging" ``` +**Additional details**: + +- A global variable defined with `value` but no `description` behaves the same as + [`variables`](#variables). + ### `when` Use `when` to configure the conditions for when jobs run. If not defined in a job, diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index bd8d7f02a17..1d3186a4047 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Format scripts and job logs **(FREE)** diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md index d3e815c742d..3d6314c8e03 100644 --- a/doc/ci/yaml/workflow.md +++ b/doc/ci/yaml/workflow.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD `workflow` keyword **(FREE)** diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md index e5d9e011230..f4774619713 100644 --- a/doc/ci/yaml/yaml_optimization.md +++ b/doc/ci/yaml/yaml_optimization.md @@ -1,7 +1,7 @@ --- 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -220,7 +220,7 @@ multiple jobs. It is similar to [YAML anchors](#anchors), but simpler and you ca [use `extends` with `includes`](#use-extends-and-include-together). `extends` supports multi-level inheritance. You should avoid using more than three levels, -but you can use as many as eleven. The following example has two levels of inheritance: +due to the additional complexity, but you can use as many as eleven. The following example has two levels of inheritance: ```yaml .tests: |