diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-12-19 14:01:45 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-12-19 14:01:45 +0300 |
| commit | 9297025d0b7ddf095eb618dfaaab2ff8f2018d8b (patch) | |
| tree | 865198c01d1824a9b098127baa3ab980c9cd2c06 /doc/ci | |
| parent | 6372471f43ee03c05a7c1f8b0c6ac6b8a7431dbe (diff) | |
Add latest changes from gitlab-org/gitlab@16-7-stable-eev16.7.0-rc42
Diffstat (limited to 'doc/ci')
121 files changed, 1463 insertions, 1144 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index f690dd3ca24..55f18987490 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Caching in GitLab CI/CD **(FREE ALL)** @@ -45,7 +45,7 @@ can't link to files outside it. To ensure maximum availability of the cache, do one or more of the following: -- [Tag your runners](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) and use the tag on jobs +- [Tag your runners](../runners/configure_runners.md#control-jobs-that-a-runner-can-run) and use the tag on jobs that share the cache. - [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-project-runner-from-being-enabled-for-other-projects). - [Use a `key`](../yaml/index.md#cachekey) that fits your workflow. For example, @@ -505,7 +505,7 @@ is stored on the machine where GitLab Runner is installed. The location also dep | Runner executor | Default path of the cache | | ---------------------- | ------------------------- | | [Shell](https://docs.gitlab.com/runner/executors/shell.html) | Locally, under the `gitlab-runner` user's home directory: `/home/gitlab-runner/cache/<user>/<project>/<cache-key>/cache.zip`. | -| [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#the-builds-and-cache-storage): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. | +| [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#configure-directories-for-the-container-build-and-cache): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. | | [Docker Machine](https://docs.gitlab.com/runner/executors/docker_machine.html) (autoscale runners) | The same as the Docker executor. | If you use cache and artifacts to store the same path in your jobs, the cache might @@ -633,7 +633,7 @@ The next time the pipeline runs, the cache is stored in a different location. You can clear the cache in the GitLab UI: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipelines**. +1. Select **Build > Pipelines**. 1. In the upper-right corner, select **Clear runner caches**. On the next commit, your CI/CD jobs use a new cache. diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index 454266942f6..d84ff3550bd 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab ChatOps **(FREE ALL)** @@ -103,7 +102,7 @@ ls: ## Trigger a CI/CD job using ChatOps -Prerequisite: +Prerequisites: - You must have at least the Developer role for the project. - The project is configured to use a slash command integration. 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 1820cf77841..0dbc165e5ee 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a Bitbucket Cloud repository **(PREMIUM ALL)** @@ -15,9 +14,8 @@ GitLab CI/CD can be used with Bitbucket Cloud by: To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In GitLab, create a project: - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. On the right of the page, select **New project**. + + 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository**. 1. Select **Repository by URL**. 1. Fill in the fields with information from the repository in Bitbucket: 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 bc61990fcd8..5c57cb1d393 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a GitHub repository **(PREMIUM ALL)** @@ -34,9 +33,7 @@ repositories: `repo` and `admin:repo_hook` so that GitLab can access your project, update commit statuses, and create a web hook to notify GitLab of new commits. 1. In GitLab, create a project: - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. On the right of the page, select **New project**. + 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository**. 1. Select **GitHub**. 1. For **Personal access token**, paste the token. @@ -63,9 +60,7 @@ To manually enable GitLab CI/CD for your repository: 1. Enter a **Token description** and update the scope to allow `repo` so that GitLab can access your project and update commit statuses. 1. In GitLab, create a project: - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. Select **New project**. + 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository** and **Repository by URL**. 1. In the **Git repository URL** field, enter the HTTPS URL for your GitHub repository. If your project is private, use the personal access token you just created for authentication. diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 76996294a96..dbe56edce7e 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD for external repositories **(PREMIUM ALL)** @@ -18,15 +17,13 @@ external repository to get the benefits of GitLab CI/CD. Connecting an external repository sets up [repository mirroring](../../user/project/repository/mirror/index.md) and creates a lightweight project with issues, merge requests, wiki, and snippets disabled. These features -[can be re-enabled later](../../user/project/settings/index.md#configure-project-features-and-permissions). +[can be re-enabled later](../../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). ## Connect to an external repository To connect to an external repository: -1. On the left sidebar, select **Search or go to**. -1. Select **View all my projects**. -1. Select **New project**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository**. 1. Select **GitHub** or **Repository by URL**. 1. Complete the fields. 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 2a73184eb7f..b80bbbc5c98 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: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to Amazon Elastic Container Service **(FREE ALL)** @@ -39,32 +39,26 @@ For the first step here, you create a demo application from a project template. Use a GitLab project template to get started. As the name suggests, these projects provide a bare-bones application built on some well-known frameworks. -1. In GitLab, select the plus icon (**{plus-square}**) at the top of the navigation bar, and select - **New project**. - +1. In GitLab on the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from template**, where you can choose from a Ruby on Rails, Spring, or NodeJS Express project. For this guide, use the Ruby on Rails template. - -  - 1. Give your project a name. In this example, it's named `ecs-demo`. Make it public so that you can take advantage of the features available in the [GitLab Ultimate plan](https://about.gitlab.com/pricing/). - 1. Select **Create project**. Now that you created a demo project, you must containerize the application and push it to the container registry. -### Push a containerized application image to GitLab Container Registry +### Push a containerized application image to GitLab container registry [ECS](https://aws.amazon.com/ecs/) is a container orchestration service, meaning that you must provide a containerized application image during the infrastructure build. To do so, you can use GitLab [Auto Build](../../../topics/autodevops/stages.md#auto-build) and [Container Registry](../../../user/packages/container_registry/index.md). -1. Go to **ecs-demo** project on GitLab. -1. Select **Setup up CI/CD**. It brings you to a `.gitlab-ci.yml` +1. On the left sidebar, select **Search or go to** and find your `ecs-demo` project. +1. Select **Set up CI/CD**. It brings you to a `.gitlab-ci.yml` creation form. 1. Copy and paste the following content into the empty `.gitlab-ci.yml`. This defines a pipeline for continuous deployment to ECS. @@ -75,7 +69,7 @@ and [Container Registry](../../../user/packages/container_registry/index.md). ``` 1. Select **Commit Changes**. It automatically triggers a new pipeline. In this pipeline, the `build` - job containerizes the application and pushes the image to [GitLab Container Registry](../../../user/packages/container_registry/index.md). + job containerizes the application and pushes the image to [GitLab container registry](../../../user/packages/container_registry/index.md).  @@ -106,7 +100,7 @@ is a specification about how the application image is started by an [ECS service 1. Select **Container Definitions > Add container**. This opens a container registration form. 1. Set `web` to **Container name**. 1. Set `registry.gitlab.com/<your-namespace>/ecs-demo/master:latest` to **Image**. - Alternatively, you can copy and paste the image path from the [GitLab Container Registry page](#push-a-containerized-application-image-to-gitlab-container-registry). + Alternatively, you can copy and paste the image path from the [GitLab container registry page](#push-a-containerized-application-image-to-gitlab-container-registry).  @@ -184,7 +178,7 @@ Now, the demo application is accessible from the internet. In this guide, HTTPS/SSL is **not** configured. You can access to the application through HTTP only (for example, `http://<ec2-ipv4-address>`). -## Setup Continuous Deployment from GitLab +## Set up Continuous Deployment from GitLab Now that you have an application running on ECS, you can set up continuous deployment from GitLab. @@ -213,7 +207,7 @@ Do not share the secret access key in a public place. You must save it in a secu You can register the access information in [GitLab CI/CD Variables](../../variables/index.md). These variables are injected into the pipeline jobs and can access the ECS API. -1. Go to **ecs-demo** project on GitLab. +1. On the left sidebar, select **Search or go to** and find your `ecs-demo` project. 1. Go to **Settings > CI/CD > Variables**. 1. Select **Add Variable** and set the following key-value pairs. @@ -230,8 +224,8 @@ These variables are injected into the pipeline jobs and can access the ECS API. Change a file in the project and see if it's reflected in the demo application on ECS: -1. Go to **ecs-demo** project on GitLab. -1. Open the file at **app > views > welcome > `index.html.erb`**. +1. On the left sidebar, select **Search or go to** and find your `ecs-demo` project. +1. Open the `app/views/welcome/index.html.erb` file. 1. Select **Edit**. 1. Change the text to `You're on ECS!`. 1. Select **Commit Changes**. This automatically triggers a new pipeline. Wait until it finishes. diff --git a/doc/ci/cloud_deployment/ecs/img/rails-template.png b/doc/ci/cloud_deployment/ecs/img/rails-template.png Binary files differdeleted file mode 100644 index 02c67f8dd21..00000000000 --- a/doc/ci/cloud_deployment/ecs/img/rails-template.png +++ /dev/null diff --git a/doc/ci/cloud_deployment/heroku.md b/doc/ci/cloud_deployment/heroku.md index 5cb6682debd..43a3b1f57e6 100644 --- a/doc/ci/cloud_deployment/heroku.md +++ b/doc/ci/cloud_deployment/heroku.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.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 16bfced9c34..14149aa6446 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to AWS from GitLab CI/CD **(FREE ALL)** @@ -61,7 +60,7 @@ deploy: GitLab provides a Docker image that includes the AWS CLI: -- Images are hosted in the GitLab Container Registry. The latest image is +- Images are hosted in the GitLab container registry. The latest image is `registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest`. - [Images are stored in a GitLab repository](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws). @@ -102,7 +101,7 @@ To deploy to your ECS cluster: | `CI_AWS_ECS_CLUSTER` | The name of the AWS ECS cluster that you're targeting for your deployments. | | `CI_AWS_ECS_SERVICE` | The name of the targeted service tied to your AWS ECS cluster. Ensure that this variable is scoped to the appropriate environment (`production`, `staging`, `review/*`). | | `CI_AWS_ECS_TASK_DEFINITION` | If the task definition is in ECS, the name of the task definition tied to the service. | - | `CI_AWS_ECS_TASK_DEFINITION_FILE` | If the task definition is a JSON file in GitLab, the filename, including the path. For example, `ci/aws/my_task_definition.json`. If the name of the task definition in your JSON file is the same name as an existing task definition in ECS, then a new revision is created when CI/CD runs. Otherwise, a brand new task definition is created, starting at revision 1. | + | `CI_AWS_ECS_TASK_DEFINITION_FILE` | If the task definition is a JSON file in GitLab, the file name, including the path. For example, `ci/aws/my_task_definition.json`. If the name of the task definition in your JSON file is the same name as an existing task definition in ECS, then a new revision is created when CI/CD runs. Otherwise, a brand new task definition is created, starting at revision 1. | WARNING: If you define both `CI_AWS_ECS_TASK_DEFINITION_FILE` and `CI_AWS_ECS_TASK_DEFINITION`, @@ -120,7 +119,7 @@ To deploy to your ECS cluster: 1. Commit and push your updated `.gitlab-ci.yml` to your project's repository. -Your application Docker image is rebuilt and pushed to the GitLab Container Registry. +Your application Docker image is rebuilt and pushed to the GitLab container registry. If your image is located in a private registry, make sure your task definition is [configured with a `repositoryCredentials` attribute](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html). diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md index dd36da86cca..b6086ed3543 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 Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in AWS to retrieve temporary credentials **(FREE ALL)** diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md index b26533562f4..d3bd8e187ba 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 Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in Azure to retrieve temporary credentials **(FREE ALL)** diff --git a/doc/ci/cloud_services/google_cloud/index.md b/doc/ci/cloud_services/google_cloud/index.md index fd8aca7045c..b38566309c9 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 Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect with GCP Workload Identity Federation **(FREE ALL)** diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index 87984c424c4..17d967e7a0d 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect to cloud services **(FREE ALL)** @@ -95,13 +95,12 @@ The condition is validated against the JWT to create a trust specifically agains - Subject or `sub`: A concatenation of metadata describing the GitLab CI/CD workflow including the group, project, branch, and tag. The `sub` field is in the following format: - `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` -| Filter type | Example | -|--------------------------------------|---------| -| Filter to main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | -| Filter to any branch | Wildcard supported. `project_path:mygroup/myproject:ref_type:branch:ref:*` | -| Filter to specific project | `project_path:mygroup/myproject:ref_type:branch:ref:main` | -| Filter to all projects under a group | Wildcard supported. `project_path:mygroup/*:ref_type:branch:ref:main` | -| Filter to a Git tag | Wildcard supported. `project_path:mygroup/*:ref_type:tag:ref:1.0` | +| Filter type | Example | +|----------------------------------------------------|---------| +| Filter to any branch | Wildcard supported. `project_path:mygroup/myproject:ref_type:branch:ref:*` | +| Filter to specific project, main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | +| Filter to all projects under a group | Wildcard supported. `project_path:mygroup/*:ref_type:branch:ref:main` | +| Filter to a Git tag | Wildcard supported. `project_path:mygroup/*:ref_type:tag:ref:1.0` | ## OIDC authorization with your cloud provider diff --git a/doc/ci/components/catalog.md b/doc/ci/components/catalog.md index 36ed7065e1c..8a7c333b5db 100644 --- a/doc/ci/components/catalog.md +++ b/doc/ci/components/catalog.md @@ -1,49 +1,11 @@ --- -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/product/ux/technical-writing/#assignments +redirect_to: '/ee/ci/components/#cicd-catalog' +remove_date: '2024-02-24' --- -# CI/CD catalog **(PREMIUM ALL EXPERIMENT)** +This document was moved to [CI/CD components](index.md#cicd-catalog). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407249) in GitLab 16.1. - -The CI/CD catalog is a list of [components repositories](index.md#components-repository), -each containing resources that you can add to your CI/CD pipelines. - -Each top level namespace has its own catalog, which contains all the releases from -components repositories hosted under it. You can create components repositories anywhere -under the desired top level namespace and the released components are available to -all projects in that namespace. - -## Add a components repository to the Catalog - -After components are added to a components repository, they can immediately be [used](index.md#use-a-component-in-a-cicd-configuration) -to build pipelines in other projects. - -However, the repository is not discoverable. You must set the project as a catalog resource -for it to be visible in the CI/CD Catalog, then other users can discover it. You should only set a repository as a catalog resource when the components are ready for usage. - -To set a project as a catalog resource: - -1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Scroll down to **CI/CD Catalog resource** and select the toggle to mark the project as a catalog resource. - -Ensure the project has a clear [description](../../user/project/settings/index.md#edit-project-name-and-description), -as the project description is displayed in the component list in the catalog. - -NOTE: -This action is not reversible, and the -component is always visible in the Catalog unless the repository is deleted. If a component has a bug or other issue, you can [create a new release](index.md#release-a-component) with an updated version. - -After the repository is set as a components repository, it appears in the CI/CD Catalog of the namespace. - -## View available components in the CI/CD Catalog - -To view the components available to your project from the CI/CD Catalog: - -1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipeline Editor**. -1. Select **Browse CI/CD Catalog**. +<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> +<!-- 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/components/index.md b/doc/ci/components/index.md index 3d46ec5bbd5..e7c286a507b 100644 --- a/doc/ci/components/index.md +++ b/doc/ci/components/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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD components **(FREE ALL BETA)** @@ -11,31 +11,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Feature flag `ci_namespace_catalog_experimental` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/394772) in GitLab 16.3. > - [Moved](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/130824) to [Beta status](../../policy/experiment-beta-support.md) in GitLab 16.6. -A CI/CD component is a reusable single pipeline configuration unit. Use them to compose an entire pipeline configuration or a small part of a larger pipeline. +A CI/CD component is a reusable single pipeline configuration unit. Use components +to create a small part of a larger pipeline, or even to compose a complete pipeline configuration. -A component can optionally take [input parameters](../yaml/inputs.md). +A component can be configured with [input parameters](../yaml/inputs.md) for more +dynamic behavior. -CI/CD components are similar to the other kinds of [configuration added with the `include` keyword](../yaml/includes.md), but have several advantages: +CI/CD components are similar to the other kinds of [configuration added with the `include` keyword](../yaml/includes.md), +but have several advantages: +- Components can be listed in the [CI/CD Catalog](#cicd-catalog). - Components can be released and used with a specific version. -- Multiple components can be combined in the same project and released with a single tag. -- Components are discoverable in the [CI/CD Catalog](catalog.md). +- Multiple components can be defined in the same project and versioned together. -## Components repository +Instead of creating your own components, you can also search for published components +that have the functionality you need in the [CI/CD Catalog](#cicd-catalog). -A components repository is a GitLab project with a repository that hosts one or more pipeline components. All components in the project are versioned and released together. +## Component project -If a component requires different versioning from other components, the component should be migrated to its own components repository. +A component project is a GitLab project with a repository that hosts one or more components. +All components in the project are versioned together, with a maximum of 10 components per project. -One component repository can have a maximum of 10 components. +If a component requires different versioning from other components, the component should be moved +to a dedicated component project. -## Create a components repository +### Create a component project -To create a components repository, you must: +To create a component project, you must: 1. [Create a new project](../../user/project/index.md#create-a-blank-project) with a `README.md` file. 1. Add a YAML configuration file for each component, following the [required directory structure](#directory-structure). - For example: ```yaml @@ -49,210 +54,256 @@ To create a components repository, you must: stage: $[[ inputs.stage ]] ``` +You can [use the component](#use-a-component) immediately, but you might want to consider +publishing the component to the [CI/CD catalog](#cicd-catalog). + ### Directory structure -A components repository can host one or more components, and must follow a mandatory file structure. +The repository must contain: -Component configurations can be saved through the following directory structure, containing: +- A `README.md` Markdown file documenting the details of all the components in the repository. +- A top level `templates/` directory that contains all the component configurations. + You can define components in this directory: + - In single files ending in `.yml` for each component, like `templates/secret-detection.yml`. + - In sub-directories containing `template.yml` files as entry points, for components + that bundle together multiple related files. For example, `templates/secret-detection/template.yml`. -- A `templates` directory at the top level of your components repository. All component configuration files - should be saved under this directory. -- Files ending in `.yml` containing the component configurations, one file per component. -- A Markdown `README.md` file explaining the details of all the components in the repository. +You should also: -For example, if the project contains a single component and a pipeline to test the component, -the file structure should be similar to: +- Configure the project's `.gitlab-ci.yml` to [test the components](#test-the-component) + and [release new versions](#publish-a-new-release). +- Add a `LICENSE.md` file with a license of your choice that covers the usage of your component. + For example the [MIT](https://opensource.org/license/mit/) or [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0#apply) + open source licenses. -```plaintext -├── templates/ -│ └── secret-detection.yml -├── README.md -└── .gitlab-ci.yml -``` +For example: -This example component could be referenced with a path similar to `gitlab.com/my-namespace/my-project/secret-detection@<version>`, -if the project is: +- If the project contains a single component, the directory structure should be similar to: -- On GitLab.com -- Named `my-project` -- In a personal namespace or group named `my-namespace` + ```plaintext + ├── templates/ + │ └── my-component.yml + ├── LICENSE.md + ├── README.md + └── .gitlab-ci.yml + ``` -The templates directory and the suffix of the configuration file should be excluded from the referenced path. +- If the project contains multiple components, then the directory structure should be similar to: -If the project contains multiple components, then the file structure should be similar to: + ```plaintext + ├── templates/ + │ ├── my-simple-component.yml + │ └── my-complex-component/ + │ ├── template.yml + │ ├── Dockerfile + │ └── test.sh + ├── LICENSE.md + ├── README.md + └── .gitlab-ci.yml + ``` -```plaintext -├── README.md -├── .gitlab-ci.yml -└── templates/ - ├── all-scans.yml - └── secret-detection.yml + In this example: + + - The `my-simple-component` component's configuration is defined in a single file. + - The `my-complex-component` component's configuration contains multiple files in a directory. + +## Use a component + +To add a component to a project's CI/CD configuration, use the [`include: component`](../yaml/index.md#includecomponent) +keyword. The component reference is formatted as `<fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>`, +for example: + +```yaml +include: + - component: gitlab.example.com/my-org/security-components/secret-detection@1.0 + inputs: + stage: build ``` -These components would be referenced with these paths: +In this example: -- `gitlab.com/my-namespace/my-project/all-scans@<version>` -- `gitlab.com/my-namespace/my-project/secret-detection@<version>` +- `gitlab.example.com` is the Fully Qualified Domain Name (FQDN) matching the GitLab host. + You can only reference components in the same GitLab instance as your project. +- `my-org/security-components` is the full path of the project containing the component. +- `secret-detection` is the component name that is defined as either a single file `templates/secret-detection.yml` + or as a directory `templates/secret-detection/` containing a `template.yml`. +- `1.0` is the [version](#component-versions) of the component. -You can also have components defined as a directory if you want to bundle together multiple related files. -In this case GitLab expects a `template.yml` file to be present: +When GitLab creates a new pipeline, the component's configuration is fetched and added to +the pipeline's configuration. -For example: +### Component versions -```plaintext -├── README.md -├── .gitlab-ci.yml -└── templates/ - └── dast - ├── docs.md - ├── Dockerfile - └── template.yml -``` +In order of highest priority first, the component version can be: -In this example, the component could be referenced with `gitlab.com/my-namespace/my-project/dast@<version>`. +- A commit SHA, for example `e3262fdd0914fa823210cdb79a8c421e2cef79d8`. +- A tag, for example: `1.0`. If a tag and commit SHA exist with the same name, + the commit SHA takes precedence over the tag. +- A branch name, for example `main`. If a branch and tag exist with the same name, + the tag takes precedence over the branch. +- `~latest`, which is a special version that always points to the most recent + [release published in the CI/CD Catalog](#publish-a-new-release). -#### Component configurations saved in any directory (deprecated) +NOTE: +The `~latest` version keyword always returns the most recent published release, not the release with +the latest semantic version. For example, if you first release `2.0.0`, and later release +a patch fix like `1.5.1`, then `~latest` returns the `1.5.1` release. +[Issue #427286](https://gitlab.com/gitlab-org/gitlab/-/issues/427286) proposes to +change this behavior. -WARNING: -Saving component configurations through this directory structure is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/415855) and should be avoided. +## CI/CD Catalog **(FREE ALL BETA)** -Components configurations can be saved through the following directory structure, containing: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407249) in GitLab 16.1 as an [experiment](../../policy/experiment-beta-support.md#experiment). +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/432045) to [beta](../../policy/experiment-beta-support.md#beta) in GitLab 16.7. -- `template.yml`: The component configuration, one file per component. If there is - only one component, this file can be in the root of the project. If there are multiple - components, each file must be in a separate subdirectory. -- `README.md`: A documentation file explaining the details of all the components in the repository. +The CI/CD Catalog is a list of projects with published CI/CD components you can use +to extend your CI/CD workflow. -For example, if the project is on GitLab.com, named `my-project`, and in a personal -namespace named `my-namespace`: +Anyone can [create a component project](#create-a-component-project) and add it to +the CI/CD Catalog, or contribute to an existing project to improve the available components. -- Containing a single component and a simple pipeline to test the component, then - the file structure might be: +### View the CI/CD Catalog - ```plaintext - ├── template.yml - ├── README.md - └── .gitlab-ci.yml - ``` +To access the CI/CD Catalog and view the published components that are available to you: - The `.gitlab-ci.yml` file is not required for a CI/CD component to work, but - [testing the component](#test-the-component) in a pipeline in the project is recommended. +1. On the left sidebar, select **Search or go to**. +1. Select **Explore**. +1. Select **CI/CD Catalog**. - This component is referenced with the path `gitlab.com/my-namespace/my-project@<version>`. +Alternatively, if you are already in the [pipeline editor](../pipeline_editor/index.md) +in your project, you can select **Browse CI/CD Catalog**. -- Containing one default component and multiple sub-components, then the file structure - might be: +NOTE: +Only public and internal projects are discoverable in the CI/CD Catalog. - ```plaintext - ├── template.yml - ├── README.md - ├── .gitlab-ci.yml - ├── unit/ - │ └── template.yml - └── integration/ - └── template.yml - ``` +### Publish a component project - These components are identified by these paths: +To publish a component project in the CI/CD catalog, you must: - - `gitlab.com/my-namespace/my-project` - - `gitlab.com/my-namespace/my-project/unit` - - `gitlab.com/my-namespace/my-project/integration` +1. Set the project as a catalog resource. +1. Publish a new release. -It is possible to have a components repository with no default component, by having -no `template.yml` in the root directory. +#### Set a component project as a catalog resource -**Additional notes:** +To make published versions of a component project visible in the CI/CD catalog, +you must set the project as a catalog resource. -Nesting of components is not possible. For example: +Prerequisites: -```plaintext -├── unit/ -│ └── template.yml -│ └── another_folder/ -│ └── nested_template.yml -``` +- You must have the Owner role in the project. -## Release a component +To set the project as a catalog resource: -To create a release for a CI/CD component, use the [`release`](../yaml/index.md#release) -keyword in a CI/CD pipeline. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn on the **CI/CD Catalog resource** toggle. -For example: +The project only becomes findable in the catalog after you publish a new release. -```yaml -create-release: - stage: deploy - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG =~ /^v\d+/ - script: echo "Creating release $CI_COMMIT_TAG" - release: - tag_name: $CI_COMMIT_TAG - description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH" -``` +#### Publish a new release -In this example, the job runs only for tags formatted as `v` + version number. -If all previous jobs succeed, the release is created. +CI/CD components can be [used](#use-a-component) without being listed in the CI/CD catalog. +However, publishing a component's releases in the catalog makes it discoverable to other users. -Like in the [component testing example](#test-the-component), you can set a component to automatically -be released after all tests pass in pipelines for new tags. +Prerequisites: -All released versions of the components repositories are displayed in the [CI/CD Catalog](catalog.md), -providing users with information about official releases. +- The project must: + - Be set as a [catalog resource](#set-a-component-project-as-a-catalog-resource). + - Have a [project description](../../user/project/working_with_projects.md#edit-project-name-and-description) defined. + - Have a `README.md` file in the root directory for the commit SHA of the tag being released. + - Have at least one [CI/CD component in the `templates/` directory](#directory-structure) + for the commit SHA of the tag being released. -Components [can be used](#use-a-component-in-a-cicd-configuration) without being released, -by using the commit SHA or ref. However, the `~latest` version keyword can only be used with released tags. +To publish a new version of the component to the catalog: -NOTE: -The `~latest` keyword always returns the most recent release, not the release with -the latest semantic version. For example, if you first release `v2.0.0`, and later release -a patch fix like `v1.5.1`, then `~latest` returns the `v1.5.1` release. -[Issue #427286](https://gitlab.com/gitlab-org/gitlab/-/issues/427286) proposes to -change this behavior. +1. Add a job to the project's `.gitlab-ci.yml` file that uses the [`release`](../yaml/index.md#release) + keyword to create the new release. For example: + + ```yaml + create-release: + stage: deploy + image: registry.gitlab.com/gitlab-org/release-cli:latest + script: echo "Creating release $CI_COMMIT_TAG" + rules: + - if: $CI_COMMIT_TAG + release: + tag_name: $CI_COMMIT_TAG + description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH" + ``` + +1. Create a [new tag](../../user/project/repository/tags/index.md#create-a-tag) for the release, + which should trigger a tag pipeline that contains the job responsible for creating the release. + You should configure the tag pipeline to [test the components](#test-the-component) before + running the release job. -## Use a component in a CI/CD configuration +After the release job completes successfully, the release is created and the new version +is published to the CI/CD catalog. + +### Unpublish a component project + +To remove a component project from the catalog, turn off the [**CI/CD Catalog resource**](#set-a-component-project-as-a-catalog-resource) +toggle in the project settings. + +WARNING: +This action destroys the metadata about the component project and its versions published +in the catalog. The project and its repository still exist, but are not visible in the catalog. + +To publish the component project in the catalog again, you need to [publish a new release](#publish-a-new-release). + +## Best practices + +This section describes some best practices for creating high quality component projects. + +### Test the component + +Testing CI/CD components as part of the development workflow is strongly recommended +and helps ensure consistent behavior. + +Test changes in a CI/CD pipeline (like any other project) by creating a `.gitlab-ci.yml` +in the root directory. Make sure to test both the behavior and potential side-effects +of the component. You can use the [GitLab API](../../api/rest/index.md) if needed. -You can add a component to a CI/CD configuration with the `include: component` keyword. For example: ```yaml include: - - component: gitlab.example.com/my-namespace/my-project@1.0 + # include the component located in the current project from the current SHA + - component: gitlab.com/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA inputs: stage: build -``` -The component is identified by a unique address in the form `<fully-qualified-domain-name>/<component-path>@<specific-version>`, -where: - -- `<fully-qualified-domain-name>` matches the GitLab host. You can only reference components - in the same GitLab instance as your project. -- `<component-path>` is the component project's full path and directory where the - component YAML file is located. -- `<specific-version>` is the version of the component. In order of highest priority first, - the version can be: - - A branch name, for example `main`. - - A commit SHA, for example `e3262fdd0914fa823210cdb79a8c421e2cef79d8`. - - A tag, for example: `1.0`. If a tag and branch exist with the same name, the tag - takes precedence over the branch. If a tag and commit SHA exist with the same name, - the commit SHA takes precedence over the tag. - - `~latest`, which is a special version that always points to the most recent released tag. - Available only if the component has been [released](#release-a-component). - -For example, for a component repository located at `gitlab-org/dast` on `gitlab.com`, -the path: - -- `gitlab.com/gitlab-org/dast@main` targets the `template.yml` in the root directory - on the `main` branch. -- `gitlab.com/gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8` targets the same file - for the specified commit SHA. -- `gitlab.com/gitlab-org/dast@1.0` targets the same file for the `1.0` tag. -- `gitlab.com/gitlab-org/dast@~latest` targets the same file for the latest release. -- `gitlab.com/gitlab-org/dast/api-scan@main` targets a different file, the `template.yml` - in the `/api-scan` directory in the component repository, for the `main` branch. +stages: [build, test, release] + +# Check if `component-job` is added. +# This example job could also test that the included component works as expected. +# You can inspect data generated by the component, use GitLab API endpoints, or third-party tools. +ensure-job-added: + stage: test + image: badouralix/curl-jq + script: + - | + route="https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/pipelines/$CI_PIPELINE_ID/jobs" + count=`curl --silent --header "PRIVATE-TOKEN: $API_TOKEN" $route | jq 'map(select(.name | contains("component-job"))) | length'` + if [ "$count" != "1" ]; then + exit 1 + fi -## Best practices +# If the pipeline is for a new tag with a semantic version, and all previous jobs succeed, +# create the release. +create-release: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG =~ /\d+/ + script: echo "Creating release $CI_COMMIT_TAG" + release: + tag_name: $CI_COMMIT_TAG + description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH" +``` + +After committing and pushing changes, the pipeline tests the component, then creates +a release if the earlier jobs pass. ### Avoid using global keywords @@ -260,13 +311,15 @@ Avoid using [global keywords](../yaml/index.md#global-keywords) in a component. Using these keywords in a component affects all jobs in a pipeline, including jobs directly defined in the main `.gitlab-ci.yml` or in other included components. -As an alternative to global keywords, instead: +As an alternative to global keywords: - Add the configuration directly to each job, even if it creates some duplication in the component configuration. -- Use the [`extends`](../yaml/index.md#extends) keyword in the component. +- Use the [`extends`](../yaml/index.md#extends) keyword in the component, but use + unique names that reduce the risk of naming conflicts when the component is merged + into the configuration. -For example, using the `default` keyword is not recommended: +For example, avoid using the `default` global keyword: ```yaml # Not recommended @@ -282,7 +335,7 @@ rspec-2: Instead, you can: -- Add the configuration to each job: +- Add the configuration to each job explicitly: ```yaml rspec-1: @@ -311,21 +364,21 @@ Instead, you can: script: bundle exec rspec dir2/ ``` -### Replace hard-coded values with inputs +### Replace hardcoded values with inputs -Avoid hard-coding values in CI/CD components. Hard-coded values might force +Avoid using hardcoded values in CI/CD components. Hardcoded values might force component users to need to review the component's internal details and adapt their pipeline to work with the component. A common keyword with problematic hard-coded values is `stage`. If a component job's -stage is set to a specific value, the pipeline using the component **must** define -the exact same stage. Additionally, if the component user wants to use a different stage, -they must [override](../yaml/includes.md#override-included-configuration-values) the configuration. +stage is hardcoded, all pipelines using the component **must** either define +the exact same stage, or [override](../yaml/includes.md#override-included-configuration-values) +the configuration. -The preferred method is to use the [`input` keyword](../yaml/inputs.md). -The component user can specify the exact value they need. +The preferred method is to use the [`input` keyword](../yaml/inputs.md) for dynamic +component configuration. The component user can specify the exact value they need. -For example: +For example, to create a component with `stage` configuration that can be defined by users: - In the component configuration: @@ -344,28 +397,28 @@ For example: script: echo integration tests ``` -- In the project using the component: +- In a project using the component: ```yaml + stages: [verify, deploy] + include: - component: gitlab.com/gitlab-org/ruby-test@1.0 inputs: stage: verify - - stages: [verify, deploy] ``` ### Replace custom CI/CD variables with inputs When using CI/CD variables in a component, evaluate if the `inputs` keyword -should be used instead. Avoid requiring a user to define custom variables to change a component's -behavior. You should try to use `inputs` for any component customization. +should be used instead. Avoid asking users to define custom variables to configure +components when `inputs` is a better solution. -Inputs are explicitly defined in the component's specs, and are better validated than variables. +Inputs are explicitly defined in the component's specs, and have better validation than variables. For example, if a required input is not passed to the component, GitLab returns a pipeline error. By contrast, if a variable is not defined, its value is empty, and there is no error. -For example, use `inputs` instead of variables to let users change a scanner's output format: +For example, use `inputs` instead of variables to configure a scanner's output format: - In the component configuration: @@ -388,17 +441,17 @@ For example, use `inputs` instead of variables to let users change a scanner's o scanner-output: yaml ``` -In other cases, CI/CD variables are still preferred, including: +In other cases, CI/CD variables might still be preferred. For example: -- Using [predefined variables](../variables/predefined_variables.md) to automatically configure +- Use [predefined variables](../variables/predefined_variables.md) to automatically configure a component to match a user's project. -- Requiring tokens or other sensitive values to be stored as [masked or protected variables in project settings](../variables/index.md#define-a-cicd-variable-in-the-ui). +- Ask users to store sensitive values as [masked or protected CI/CD variables in project settings](../variables/index.md#define-a-cicd-variable-in-the-ui). ### Use semantic versioning -When tagging and releasing new versions of components, you should use [semantic versioning](https://semver.org). -Semantic versioning is the standard for communicating that a change is a major, minor, patch, -or other kind of change. +When tagging and [releasing new versions](#publish-a-new-release) of components, +you should use [semantic versioning](https://semver.org). Semantic versioning is the standard +for communicating that a change is a major, minor, patch, or other kind of change. You should use at least the `major.minor` format, as this is widely understood. For example, `2.0` or `2.1`. @@ -410,66 +463,32 @@ Other examples of semantic versioning: - `1.0.0-alpha` - `3.0.0-rc1` -### Test the component - -Testing CI/CD components as part of the development workflow is strongly recommended -and helps ensure consistent behavior. - -Test changes in a CI/CD pipeline (like any other project) by creating a `.gitlab-ci.yml` -in the root directory. - -For example: - -```yaml -include: - # include the component located in the current project from the current SHA - - component: gitlab.com/$CI_PROJECT_PATH/my-project@$CI_COMMIT_SHA - inputs: - stage: build - -stages: [build, test, release] - -# Expect `component-job` is added. -# This example tests that the included component works as expected. -# You can inspect data generated by the component, use GitLab API endpoints or third-party tools. -ensure-job-added: - stage: test - image: badouralix/curl-jq - script: - - | - route="https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/pipelines/$CI_PIPELINE_ID/jobs" - count=`curl --silent --header "PRIVATE-TOKEN: $API_TOKEN" $route | jq 'map(select(.name | contains("component-job"))) | length'` - if [ "$count" != "1" ]; then - exit 1 - fi - -# If we are tagging a release with a specific convention ("v" + number) and all -# previous checks succeeded, we proceed with creating a release automatically. -create-release: - stage: release - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG =~ /^v\d+/ - script: echo "Creating release $CI_COMMIT_TAG" - release: - tag_name: $CI_COMMIT_TAG - description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH" -``` - -After committing and pushing changes, the pipeline tests the component, then releases it if the test passes. - ## Convert a CI/CD template to a component Any existing CI/CD template that you use in projects by using the `include:` syntax can be converted to a CI/CD component: -1. Decide if you want the component to be part of an existing [components repository](index.md#components-repository) - to be grouped with other components, or create and set up a new components repository. -1. Create a YAML file in the components repository according to the expected [directory structure](index.md#directory-structure). +1. Decide if you want the component to be grouped with other components as part of + an existing [component project](index.md#component-project), or [create a new component project](#create-a-component-project). +1. Create a YAML file in the component project according to the [directory structure](index.md#directory-structure). 1. Copy the content of the original template YAML file into the new component YAML file. 1. Refactor the new component's configuration to: - Follow the [best practices](index.md#best-practices) for components. - Improve the configuration, for example by enabling [merge request pipelines](../pipelines/merge_request_pipelines.md) or making it [more efficient](../pipelines/pipeline_efficiency.md). 1. Leverage the `.gitlab-ci.yml` in the components repository to [test changes to the component](index.md#test-the-component). -1. Tag and [release the component](index.md#release-a-component). +1. Tag and [release the component](#publish-a-new-release). + +## Troubleshooting + +### `content not found` message + +You might receive an error message similar to the following when using the `~latest` +version qualifier to reference a component hosted by a [catalog resource](#set-a-component-project-as-a-catalog-resource): + +```plaintext +This GitLab CI configuration is invalid: component 'gitlab.com/my-namespace/my-project/my-component@~latest' - content not found` +``` + +The `~latest` behavior [was updated](https://gitlab.com/gitlab-org/gitlab/-/issues/429707) +in GitLab 16.7. It now refers to the latest published version of the catalog resource. To resolve this issue, [create a new release](#publish-a-new-release). diff --git a/doc/ci/debugging.md b/doc/ci/debugging.md index 5bcf834b61d..8a60b5f649e 100644 --- a/doc/ci/debugging.md +++ b/doc/ci/debugging.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debugging CI/CD pipelines **(FREE ALL)** @@ -163,7 +162,7 @@ For help with a specific area, see: - [Caching](caching/index.md#troubleshooting). - [CI/CD job tokens](jobs/ci_job_token.md). -- [Container Registry](../user/packages/container_registry/troubleshoot_container_registry.md). +- [Container registry](../user/packages/container_registry/troubleshoot_container_registry.md). - [Docker](docker/using_docker_build.md#troubleshooting). - [Downstream pipelines](pipelines/downstream_pipelines.md#troubleshooting). - [Environments](environments/deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time). @@ -293,3 +292,8 @@ These errors can happen if the following are both true: To resolve this issue, add any projects with CI/CD jobs that fetch images from the container registry to the target project's [job token allowlist](jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token). + +These errors might also happen when trying to use a [project access token](../user/project/settings/project_access_tokens.md) +to access images in another project. Project access tokens are scoped to one project, +and therefore cannot access images in other projects. You must use [a different token type](../security/token_overview.md) +with wider scope. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index a1163a3acff..fab784783f6 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Directed Acyclic Graph **(FREE ALL)** diff --git a/doc/ci/docker/authenticate_registry.md b/doc/ci/docker/authenticate_registry.md index 28edb5140dd..fbf05e9ef7a 100644 --- a/doc/ci/docker/authenticate_registry.md +++ b/doc/ci/docker/authenticate_registry.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authenticate with registry in Docker-in-Docker diff --git a/doc/ci/docker/buildah_rootless_tutorial.md b/doc/ci/docker/buildah_rootless_tutorial.md index fdb33fd4a8b..0a094374fd0 100644 --- a/doc/ci/docker/buildah_rootless_tutorial.md +++ b/doc/ci/docker/buildah_rootless_tutorial.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Use Buildah in a rootless container with GitLab Runner Operator on OpenShift **(FREE)** @@ -52,8 +51,8 @@ We start by preparing a custom image based on the `quay.io/buildah/stable:v1.23. EOF ``` -1. Build and push the Buildah image to a Container Registry. Let's push to the - [GitLab Container Registry](../../user/packages/container_registry/index.md): +1. Build and push the Buildah image to a container registry. Let's push to the + [GitLab container registry](../../user/packages/container_registry/index.md): ```shell docker build -f Containerfile-buildah -t registry.example.com/group/project/buildah:1.23.1 . diff --git a/doc/ci/docker/docker_layer_caching.md b/doc/ci/docker/docker_layer_caching.md index b34b58ce964..e8f2636db0a 100644 --- a/doc/ci/docker/docker_layer_caching.md +++ b/doc/ci/docker/docker_layer_caching.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Make Docker-in-Docker builds faster with Docker layer caching diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 49a9e1f8eea..f4e7587f02e 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Docker integration **(FREE ALL)** @@ -15,7 +14,7 @@ There are two primary ways to incorporate [Docker](https://www.docker.com) into an application. These jobs can run in Docker containers. For example, you can tell GitLab CI/CD to use a Node image that's hosted on Docker Hub - or in the GitLab Container Registry. Your job then runs in a container that's based on the image. + or in the GitLab container registry. Your job then runs in a container that's based on the image. The container has all the Node dependencies you need to build your app. - **Use [Docker](using_docker_build.md) or [kaniko](using_kaniko.md) to build Docker images.** diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 2505089e4be..beaa2291eea 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Docker to build Docker images **(FREE ALL)** @@ -319,6 +318,63 @@ To use Docker-in-Docker with TLS enabled in Kubernetes: - docker run my-docker-image /script/to/run/tests ``` +##### Docker-in-Docker with TLS disabled in Kubernetes + +To use Docker-in-Docker with TLS disabled in Kubernetes, you must adapt the example above to: + +- Remove the `[[runners.kubernetes.volumes.empty_dir]]` section from the `values.yml` file. +- Change the port from `2376` to `2375` with `DOCKER_HOST: tcp://docker:2375`. +- Instruct Docker to start with TLS disabled with `DOCKER_TLS_CERTDIR: ""`. + +For example: + +1. Using the + [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), update the + [`values.yml` file](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/00c1a2098f303dffb910714752e9a981e119f5b5/values.yaml#L133-137): + + ```yaml + runners: + config: | + [[runners]] + [runners.kubernetes] + image = "ubuntu:20.04" + privileged = true + ``` + +1. You can now use `docker` in the job script. You should include the + `docker:24.0.5-dind` service: + + ```yaml + default: + image: docker:24.0.5 + services: + - docker:24.0.5-dind + before_script: + - docker info + + variables: + # When using dind service, you must instruct Docker to talk with + # the daemon started inside of the service. The daemon is available + # with a network connection instead of the default + # /var/run/docker.sock socket. + DOCKER_HOST: tcp://docker:2375 + # + # The 'docker' hostname is the alias of the service container as described at + # https://docs.gitlab.com/ee/ci/services/#accessing-the-services. + # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, + # the variable must be set to tcp://localhost:2376 because of how the + # Kubernetes executor connects services to the job container + # DOCKER_HOST: tcp://localhost:2376 + # + # This instructs Docker not to start over TLS. + DOCKER_TLS_CERTDIR: "" + build: + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests + ``` + #### Known issues with Docker-in-Docker Docker-in-Docker is the recommended configuration, but you should be aware of the following issues: @@ -651,11 +707,11 @@ of the following executors: In this example, you use Buildah to: 1. Build a Docker image. -1. Push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). +1. Push it to [GitLab container registry](../../user/packages/container_registry/index.md). In the last step, Buildah uses the `Dockerfile` under the root directory of the project to build the Docker image. Finally, it pushes the image to the -project's Container Registry: +project's container registry: ```yaml build: @@ -671,7 +727,7 @@ build: BUILDAH_FORMAT: docker FQ_IMAGE_NAME: "$CI_REGISTRY_IMAGE/test" before_script: - # GitLab Container Registry credentials taken from the + # GitLab container registry credentials taken from the # [predefined CI/CD variables](../variables/index.md#predefined-cicd-variables) # to authenticate to the registry. - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY @@ -685,10 +741,10 @@ build: If you are using GitLab Runner Operator deployed to an OpenShift cluster, try the [tutorial for using Buildah to build images in rootless container](buildah_rootless_tutorial.md). -## Use the GitLab Container Registry +## Use the GitLab container registry After you've built a Docker image, you can push it to the -[GitLab Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd). +[GitLab container registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd). ## Troubleshooting diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index dd6cd2099a9..7e24016a455 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run your CI/CD jobs in Docker containers **(FREE ALL)** @@ -203,7 +202,7 @@ Look for the `[runners.docker]` section: The image and services defined this way are added to all jobs run by that runner. -## Access an image from a private Container Registry +## Access an image from a private container registry To access private container registries, the GitLab Runner process can use: @@ -534,11 +533,11 @@ and update Docker images on Amazon ECR, without using manual credential manageme build-image: stage: build script: - - echo "Logging into GitLab Container Registry..." + - echo "Logging into GitLab container registry..." - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - echo "Building Docker image..." - docker build --build-arg GITLAB_RUNNER_VERSION=${GITLAB_RUNNER_VERSION} --build-arg AWS_CLI_VERSION=${AWS_CLI_VERSION} -t ${IMAGE_NAME} . - - echo "Pushing Docker image to GitLab Container Registry..." + - echo "Pushing Docker image to GitLab container registry..." - docker push ${IMAGE_NAME} rules: - changes: diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 8ab13c7154d..97cdbf79d02 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use kaniko to build Docker images **(FREE ALL)** @@ -43,16 +42,16 @@ few important details: In the following example, kaniko is used to: 1. Build a Docker image. -1. Then push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). +1. Then push it to [GitLab container registry](../../user/packages/container_registry/index.md). The job runs only when a tag is pushed. A `config.json` file is created under -`/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the +`/kaniko/.docker` with the needed GitLab container registry credentials taken from the [predefined CI/CD variables](../variables/index.md#predefined-cicd-variables) GitLab CI/CD provides. These are automatically read by the Kaniko tool. In the last step, kaniko uses the `Dockerfile` under the root directory of the project, builds the Docker image and pushes it to the -project's Container Registry while tagging it with the Git tag: +project's container registry while tagging it with the Git tag: ```yaml build: diff --git a/doc/ci/environments/configure_kubernetes_deployments.md b/doc/ci/environments/configure_kubernetes_deployments.md index e618aae7cae..715942985e7 100644 --- a/doc/ci/environments/configure_kubernetes_deployments.md +++ b/doc/ci/environments/configure_kubernetes_deployments.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Kubernetes deployments (deprecated) diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index b14ee5eb3eb..f1c7b412c6f 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Require approvals prior to deploying to a Protected Environment --- @@ -23,7 +23,7 @@ require approvals for deployments to production environments. You can require approvals for deployments to protected environments in a project. -Prerequisite: +Prerequisites: - To update an environment, you must have at least the Maintainer role. @@ -215,11 +215,7 @@ The approval status details are shown: ## View blocked deployments -Use the UI or API to review the status of your deployments, including whether a deployment is blocked. - -::Tabs - -:::TabTitle With the UI +Review the status of your deployments, including whether a deployment is blocked. To view your deployments: @@ -229,16 +225,9 @@ To view your deployments: A deployment with the **blocked** label is blocked. -:::TabTitle With the API - -To view your deployments: - -- Using the [deployments API](../../api/deployments.md#get-a-specific-deployment), get a specific deployment, or a list of all deployments in a project. - +To view your deployments, you can also [use the API](../../api/deployments.md#get-a-specific-deployment). The `status` field indicates whether a deployment is blocked. -::EndTabs - ## Related topics - [Deployment approvals feature epic](https://gitlab.com/groups/gitlab-org/-/epics/6832) diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index b34fc61ba66..ec6d2c482cd 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deployment safety **(FREE ALL)** diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 0beaf2b8888..24a619d9f10 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environments Dashboard **(PREMIUM ALL)** diff --git a/doc/ci/environments/external_deployment_tools.md b/doc/ci/environments/external_deployment_tools.md index ac31d196887..29c811b68be 100644 --- a/doc/ci/environments/external_deployment_tools.md +++ b/doc/ci/environments/external_deployment_tools.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Track deployments of an external deployment tool **(FREE ALL)** diff --git a/doc/ci/environments/img/kubernetes_summary_ui.png b/doc/ci/environments/img/kubernetes_summary_ui.png Binary files differnew file mode 100644 index 00000000000..ce51cd8e96f --- /dev/null +++ b/doc/ci/environments/img/kubernetes_summary_ui.png diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index 309e311e252..9dd5e676924 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incremental rollouts with GitLab CI/CD **(FREE ALL)** diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 8306746dd1f..03c9a152d98 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environments and deployments **(FREE ALL)** diff --git a/doc/ci/environments/kubernetes_dashboard.md b/doc/ci/environments/kubernetes_dashboard.md index 42fa560ad76..9f5be975cdf 100644 --- a/doc/ci/environments/kubernetes_dashboard.md +++ b/doc/ci/environments/kubernetes_dashboard.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dashboard for Kubernetes **(FREE ALL BETA)** @@ -15,6 +14,8 @@ Use the Dashboard for Kubernetes to understand the status of your clusters with The dashboard works with every connected Kubernetes cluster, whether you deployed them with CI/CD or GitOps. + + ## Configure a dashboard > - Filtering resources by namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403618) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `kubernetes_namespace_for_environment`. Disabled by default. @@ -31,7 +32,9 @@ Prerequisites: - The agent for Kubernetes must be shared with the environment's project, or its parent group, using the [`user_access`](../../user/clusters/agent/user_access.md) keyword. - Self-managed only. KAS is running on the GitLab subdomain. For example, `kas.example.com` and `example.com`. -### The environment already exists +::Tabs + +:::TabTitle The environment already exists 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Environments**. @@ -42,7 +45,7 @@ Prerequisites: 1. Optional. From the **Flux resource** dropdown list, select a Flux resource. 1. Select **Save**. -### The environment doesn't exist +:::TabTitle The environment doesn't exist 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Environments**. @@ -53,18 +56,16 @@ Prerequisites: 1. Optional. From the **Flux resource** dropdown list, select a Flux resource. 1. Select **Save**. -## View a dashboard +::EndTabs -> Kubernetes watch API integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422945) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `k8s_watch_api`. Disabled by default. +## View a dashboard -FLAG: -On self-managed GitLab, by default the Kubernetes watch API integration is not available. -To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `k8s_watch_api`. -On GitLab.com, this feature is not available. +> - Kubernetes watch API integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422945) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `k8s_watch_api`. Disabled by default. +> - Kubernetes watch API integration [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136831) in GitLab 16.7. View a dashboard to see the status of any connected clusters. If the `k8s_watch_api` feature flag is enabled, the status of your -pods and Flux reconciliation updates in real time. +Kubernetes resources and Flux reconciliation updates in real time. To view a configured dashboard: diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index e594ff725a4..69f7c558b8b 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected environments **(PREMIUM ALL)** @@ -27,6 +27,7 @@ Maintainer role. Prerequisites: - 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 does not show up in the dropdown list. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). +- When granting **Allowed to deploy** and **Approvers** permissions to a group or project by using the settings UI, only direct members of the group or project receive these permissions. To grant these permissions to inherited members also, [use the API](../../api/protected_environments.md#group-inheritance-types). For more information see [issue #422392](https://gitlab.com/gitlab-org/gitlab/-/issues/422392). To protect an environment: diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index f494ff6dffb..ed891b46999 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authenticating and reading secrets with HashiCorp Vault **(PREMIUM ALL)** @@ -191,14 +190,6 @@ This example uses [bound claims](https://developer.hashicorp.com/vault/api-docs/ Combined with [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets. -To use the same policy for a list of projects, use `namespace_id`: - -```json -"bound_claims": { - "namespace_id": ["12", "22", "37"] -} -``` - Any of the claims [included in the JWT](#how-it-works) can be matched against a list of values in the bound claims. For example: @@ -212,10 +203,17 @@ in the bound claims. For example: } "bound_claims": { + "namespace_id": ["10", "20", "30"] +} + +"bound_claims": { "project_id": ["12", "22", "37"] } ``` +- If only `namespace_id` is used, all projects in the namespace are allowed. +- If both `namespace_id` and `project_id` are used, Vault first checks if the project's namespace is in `namespace_id`. If not, it then checks if the project is in `project_id`. + [`token_explicit_max_ttl`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds. [`user_claim`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login. diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index dfdaa1866c3..149f99e8a66 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Running Composer and npm scripts with deployment via SCP in GitLab CI/CD **(FREE ALL)** diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index 2be800efcbb..0ffc09c8646 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Dpl as a deployment tool **(FREE ALL)** 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 10ec18a6147..556af355b1a 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.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.' diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index aa3be8f2ab0..f618b6beec9 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD examples **(FREE ALL)** @@ -27,7 +26,7 @@ The following table lists examples with step-by-step tutorials that are containe | GitLab Pages | See the [GitLab Pages](../../user/project/pages/index.md) documentation for a complete example of deploying a static site. | | End-to-end testing | [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md). | | Multi project pipeline | [Build, test deploy using multi project pipeline](https://gitlab.com/gitlab-examples/upstream-project). | -| npm with semantic-release | [Publish npm packages to the GitLab Package Registry using semantic-release](semantic-release.md). | +| npm with semantic-release | [Publish npm packages to the GitLab package registry using semantic-release](semantic-release.md). | | PHP with Laravel, Envoy | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md). | | PHP with npm, SCP | [Running Composer and npm scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md). | | PHP with PHPUnit, `atoum` | [Testing PHP projects](php.md). | @@ -150,7 +149,7 @@ For examples of others who have implemented GitLab CI/CD, see: - [Test all the things in GitLab CI with Docker by example](https://about.gitlab.com/blog/2018/02/05/test-all-the-things-gitlab-ci-docker-examples/) - [A Craftsman looks at continuous integration](https://about.gitlab.com/blog/2018/01/17/craftsman-looks-at-continuous-integration/) - [Go tools and GitLab: How to do continuous integration like a boss](https://about.gitlab.com/blog/2017/11/27/go-tools-and-gitlab-how-to-do-continuous-integration-like-a-boss/) -- [GitBot – automating boring Git operations with CI](https://about.gitlab.com/blog/2017/11/02/automating-boring-git-operations-gitlab-ci/) +- [GitBot - automating boring Git operations with CI](https://about.gitlab.com/blog/2017/11/02/automating-boring-git-operations-gitlab-ci/) - [How to use GitLab CI for Vue.js](https://about.gitlab.com/blog/2017/09/12/vuejs-app-gitlab/) - Video: [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195) - [Dockerizing GitLab Review Apps](https://about.gitlab.com/blog/2017/07/11/dockerizing-review-apps/) 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 ea936b66d31..25a0750e5eb 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments author: Mehran Rasulian author_gitlab: mehranrasulian --- @@ -430,19 +430,19 @@ We added the [official PHP 7.4 Docker image](https://hub.docker.com/_/php), whic We used `docker-php-ext-install` (provided by the official PHP Docker image) to install the PHP extensions we need. -#### Setting Up GitLab Container Registry +#### Setting Up GitLab container registry -Now that we have our `Dockerfile` let's build and push it to our [GitLab Container Registry](../../../user/packages/container_registry/index.md). +Now that we have our `Dockerfile` let's build and push it to our [GitLab container registry](../../../user/packages/container_registry/index.md). -> The registry is the place to store and tag images for later use. Developers may want to maintain their own registry for private, company images, or for throw-away images used only in testing. Using GitLab Container Registry means you don't need to set up and administer yet another service or use a public registry. +> The registry is the place to store and tag images for later use. Developers may want to maintain their own registry for private, company images, or for throw-away images used only in testing. Using GitLab container registry means you don't need to set up and administer yet another service or use a public registry. On your GitLab project repository navigate to the **Registry** tab.  -You may need to enable the Container Registry for your project to see this tab. You'll find it under your project's **Settings > General > Visibility, project features, permissions**. +You may need to enable the container registry for your project to see this tab. You'll find it under your project's **Settings > General > Visibility, project features, permissions**. -To start using Container Registry on our machine, we first need to sign in to the GitLab registry using our GitLab username and password. +To start using container registry on our machine, we first need to sign in to the GitLab registry using our GitLab username and password. Make sure you have [Docker](https://docs.docker.com/engine/install/) installed on our machine, then run the following commands: diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 0e0d40f12f6..12d3cf32d98 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing PHP projects **(FREE ALL)** diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index 356a3d1d63e..6a21b6d3d83 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -1,19 +1,19 @@ --- stage: Package group: Package Registry -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Publish npm packages to the GitLab Package Registry using semantic-release **(FREE ALL)** +# Publish npm packages to the GitLab package registry using semantic-release **(FREE ALL)** -This guide demonstrates how to automatically publish npm packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). +This guide demonstrates how to automatically publish npm packages to the [GitLab package registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). You can also view or fork the complete [example source](https://gitlab.com/gitlab-examples/semantic-release-npm). ## Initialize the module 1. Open a terminal and navigate to the project's repository. -1. Run `npm init`. Name the module according to [the Package Registry's naming conventions](../../user/packages/npm_registry/index.md#naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`. +1. Run `npm init`. Name the module according to [the package registry's naming conventions](../../user/packages/npm_registry/index.md#naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`. 1. Install the following npm packages: @@ -82,7 +82,7 @@ publish: This example configures the pipeline with a single job, `publish`, which runs `semantic-release`. The semantic-release library publishes new versions of the npm package and creates new GitLab releases (if necessary). -The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the Package Registry during the `publish` job. +The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the package registry during the `publish` job. ## Set up CI/CD variables diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 2561ab6465e..747c2abb61a 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Git submodules with GitLab CI/CD **(FREE ALL)** diff --git a/doc/ci/index.md b/doc/ci/index.md index c0c63d13d3a..beb7fffeb8a 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -1,9 +1,8 @@ --- 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments 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 --- # Get started with GitLab CI/CD **(FREE ALL)** @@ -105,6 +104,6 @@ A CI/CD component is a reusable single pipeline configuration unit. Use them to - [Five teams that made the switch to GitLab CI/CD](https://about.gitlab.com/blog/2019/04/25/5-teams-that-made-the-switch-to-gitlab-ci-cd/). - [Make the case for CI/CD in your organization](https://about.gitlab.com/why-gitlab/). - Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) from 30 days to under 8 hours with GitLab. -- Use the [GitLab Workflow VS Code extension](../user/project/repository/vscode.md) to +- Use the [GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md) to [validate your configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration) and [view your pipeline status](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 1125061d830..4108ab93797 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Interactive web terminals **(FREE ALL)** diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md deleted file mode 100644 index 57731a96a90..00000000000 --- a/doc/ci/introduction/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../index.md' -remove_date: '2023-11-24' ---- - -This document was moved to [another location](../index.md). - -<!-- This redirect file can be deleted after <2023-11-24>. --> -<!-- 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/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index cf8b4ccd092..ba2d63c12e4 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 Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD job token **(FREE ALL)** @@ -12,11 +12,11 @@ When a pipeline job is about to run, GitLab generates a unique token and injects You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - Packages: - - [Package Registry](../../user/packages/package_registry/index.md#to-build-packages). + - [Package registry](../../user/packages/package_registry/index.md#to-build-packages). - [Packages API](../../api/packages.md) (project-level). - - [Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) + - [Container registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). - - [Container Registry API](../../api/container_registry.md) + - [Container registry API](../../api/container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled). - [Get job artifacts](../../api/job_artifacts.md#get-job-artifacts). - [Get job token's job](../../api/jobs.md#get-job-tokens-job). @@ -120,12 +120,12 @@ the following actions without being added to the allowlist: To limit access to these actions to only the projects on the allowlist, set the visibility of each feature to be only accessible to project members: -Prerequisite: +Prerequisites: - You must have the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Set the visibility to **Only project members** for the features you want to restrict access to. - The ability to fetch artifacts is controlled by the CI/CD visibility setting. @@ -145,7 +145,7 @@ your maintainers, the job token could be used in an attempt to access your proje You can disable the job token scope allowlist for testing or a similar reason, but you should enable it again as soon as possible. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -166,7 +166,7 @@ You can also disable the allowlist [with the API](../../api/graphql/reference/in You can add projects to the allowlist for a project. Projects added to the allowlist can make API calls from running pipelines by using the CI/CD job token. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role in the current project. If the allowed project is internal or private, you must have at least the Guest role in that project. @@ -210,7 +210,7 @@ to make an API request to project `B`, then `B` must be added to the allowlist f > **Limit CI_JOB_TOKEN access** setting [renamed to **Limit access _from_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. -Prerequisite: +Prerequisites: - You must not have more than 200 projects added to the token's scope. diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index b5fc32e69dc..f4836f93234 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs **(FREE ALL)** @@ -375,6 +375,14 @@ job1: - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K" ``` +### Full screen mode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363617) in GitLab 16.7. + +You can view the contents of a job log in full screen mode by clicking **Show full screen**. + +To use full screen mode, your web browser must also support it. If your web browser does not support full screen mode, then the option is not available. + ## Deployment jobs Deployment jobs are a specific kind of CI job in that they deploy code to diff --git a/doc/ci/jobs/job_artifacts.md b/doc/ci/jobs/job_artifacts.md index b6269918ed9..f93068faf01 100644 --- a/doc/ci/jobs/job_artifacts.md +++ b/doc/ci/jobs/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job artifacts **(FREE ALL)** @@ -67,6 +67,8 @@ is used. To prevent artifacts from expiring, you can select **Keep** from the job details page. The option is not available when an artifact has no expiry set. +By default, the [latest artifacts are always kept](#keep-artifacts-from-most-recent-successful-jobs). + ### With a dynamically defined name You can use [CI/CD variables](../variables/index.md) to dynamically define the @@ -227,17 +229,21 @@ unless the report is added as a regular artifact with `artifacts:paths`. You can download the artifacts archive for a specific job with a publicly accessible URL for the [job artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive). -For example, to download the latest artifacts of a job named `build` in the `main` branch of a project on GitLab.com: +For example: -```plaintext -https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build -``` +- To download the latest artifacts of a job named `build` in the `main` branch of a project on GitLab.com: -For example, to download the file `review/index.html` from the latest job named `build` in the `main` branch of a project on GitLab.com: + ```plaintext + https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build + ``` -```plaintext -https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build -``` +- To download the file `review/index.html` from the latest job named `build` in the `main` branch of a project on GitLab.com: + + ```plaintext + https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build + ``` + + Files returned by this endpoint always have the `plain/text` content type. In both examples, replace `<project-id>` with a valid project ID, found at the top of the project details page. @@ -327,15 +333,21 @@ With this configuration, GitLab adds **artifact 1** as a link to `file.txt` to t > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4. > - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8. +> - Artifacts for [blocked](https://gitlab.com/gitlab-org/gitlab/-/issues/387087) or [failed](https://gitlab.com/gitlab-org/gitlab/-/issues/266958) pipelines no longer kept indefinitely in GitLab 16.7. + +By default artifacts are always kept for successful pipelines for the most recent commit on each ref. +Any [`expire_in`](#with-an-expiry) configuration does not apply to the most recent artifacts. -By default artifacts are always kept for successful pipelines for the most recent commit on -each ref. This means that the latest artifacts do not immediately expire according -to the `expire_in` configuration. +A pipeline's artifacts are only deleted according to the `expire_in` configuration +if a new pipeline runs for the same ref and: -If a pipeline for a new commit on the same ref completes successfully, the previous pipeline's -artifacts are deleted according to the `expire_in` configuration. The artifacts -of the new pipeline are kept automatically. If multiple pipelines run for the most -recent commit on the ref, all artifacts are kept. +- Succeeds. +- Fails. +- Stops running due to being blocked by a manual job. + +Additionally, artifacts are kept for the ref's last successful pipeline even if it +is not the latest pipeline. As a result, if a new pipeline run fails, the last successful pipeline's +artifacts are still kept. Keeping the latest artifacts can use a large amount of storage space in projects with a lot of jobs or large artifacts. If the latest artifacts are not needed in @@ -352,7 +364,3 @@ Then the artifacts in the earlier pipeline for that ref are allowed to expire to You can disable this behavior for all projects on a self-managed instance in the [instance's CI/CD settings](../../administration/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). - -When **Keep artifacts from most recent successful jobs** is enabled, artifacts are always kept for [blocked](job_control.md#types-of-manual-jobs) -pipelines. These artifacts expire only after the blocking job is triggered and the pipeline completes. -[Issue 387087](https://gitlab.com/gitlab-org/gitlab/-/issues/387087) proposes to change this behavior. diff --git a/doc/ci/jobs/job_artifacts_troubleshooting.md b/doc/ci/jobs/job_artifacts_troubleshooting.md index f2efa8da9eb..0b7777d2d82 100644 --- a/doc/ci/jobs/job_artifacts_troubleshooting.md +++ b/doc/ci/jobs/job_artifacts_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting job artifacts @@ -29,7 +29,7 @@ If job artifacts are using too much disk space, see the This message appears in job logs when a the runner can't find the file to upload. Either the path to the file is incorrect, or the file was not created. You can check the job -log for other errors or warnings that specify the filename and why it wasn't +log for other errors or warnings that specify the file name and why it wasn't generated. For more detailed job logs, you can [enable CI/CD debug logging](../variables/index.md#enable-debug-logging) diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index 0c8e4fc593f..b432106a2d8 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Choose when to run jobs **(FREE ALL)** @@ -1080,6 +1080,14 @@ produce an `invalid expression syntax` error. Pattern matching is case-sensitive by default. Use the `i` flag modifier to make a pattern case-insensitive. For example: `/pattern/i`. +NOTE: +When using the `=~` character, make sure the right side of the comparison always contains +a valid regular expression. If the right side of the comparison is not a valid regular expression +enclosed with `/` characters, the expression evaluates in an unexpected way. In that case, +the comparison checks if the left side is a substring of the right side. For example, +`"23" =~ "1234"` evaluates to true, which is the opposite of `"23" =~ /1234/`, which evaluates to false. +You should not configure your pipeline to rely on this behavior. + #### Store the regex pattern in a variable > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `ci_fix_rules_if_comparison_with_regexp_variable`, disabled by default. diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 2b54c645807..88ea4cd05d7 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Validate GitLab CI/CD configuration **(FREE ALL)** @@ -15,7 +15,7 @@ If you use the [pipeline editor](pipeline_editor/index.md), it verifies configur syntax automatically. If you use VS Code, you can validate your CI/CD configuration with the -[GitLab Workflow VS Code extension](../user/project/repository/vscode.md). +[GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md). ## Check CI/CD syntax diff --git a/doc/ci/migration/bamboo.md b/doc/ci/migration/bamboo.md index 93091d2a30a..ea9dd666176 100644 --- a/doc/ci/migration/bamboo.md +++ b/doc/ci/migration/bamboo.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Bamboo **(FREE ALL)** diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 5b171a646f5..f397a1cf733 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,13 +1,12 @@ --- 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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from CircleCI **(FREE ALL)** -If you are currently using CircleCI, you can migrate your CI/CD pipelines to [GitLab CI/CD](../introduction/index.md), +If you are currently using CircleCI, you can migrate your CI/CD pipelines to [GitLab CI/CD](../index.md), and start making use of all its powerful features. We have collected several resources that you may find useful before starting to migrate. diff --git a/doc/ci/migration/examples/jenkins-maven.md b/doc/ci/migration/examples/jenkins-maven.md index 0ed08357eef..858f0272502 100644 --- a/doc/ci/migration/examples/jenkins-maven.md +++ b/doc/ci/migration/examples/jenkins-maven.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate a Maven build from Jenkins to GitLab CI/CD diff --git a/doc/ci/migration/github_actions.md b/doc/ci/migration/github_actions.md index 46d15f506ac..ec55f129c1e 100644 --- a/doc/ci/migration/github_actions.md +++ b/doc/ci/migration/github_actions.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from GitHub Actions **(FREE ALL)** @@ -467,7 +466,7 @@ Some key details about runners: - Runners can be [configured](../runners/runners_scope.md) to be shared across an instance, a group, or dedicated to a single project. -- You can use the [`tags` keyword](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) +- You can use the [`tags` keyword](../runners/configure_runners.md#control-jobs-that-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 4352b495e7b..f430b1ac7b9 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Jenkins **(FREE ALL)** @@ -483,7 +482,7 @@ Some key details about runners: - Runners can be [configured](../runners/runners_scope.md) to be shared across an instance, a group, or dedicated to a single project. -- You can use the [`tags` keyword](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) +- You can use the [`tags` keyword](../runners/configure_runners.md#control-jobs-that-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). diff --git a/doc/ci/migration/plan_a_migration.md b/doc/ci/migration/plan_a_migration.md index 22c4645d6c2..c6e4baabb92 100644 --- a/doc/ci/migration/plan_a_migration.md +++ b/doc/ci/migration/plan_a_migration.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Plan a migration from another tool to GitLab CI/CD diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md index 4e1a0f4683c..e871a95d29f 100644 --- a/doc/ci/mobile_devops.md +++ b/doc/ci/mobile_devops.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mobile DevOps **(EXPERIMENT)** diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 1dc6bc05e71..cc7b032a487 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline editor **(FREE ALL)** @@ -45,7 +44,11 @@ The **Lint** tab is replaced with the **Validate** tab in GitLab 15.3. The lint in a successful [pipeline simulation](#simulate-a-cicd-pipeline). To test the validity of your GitLab CI/CD configuration before committing the changes, -you can use the CI lint tool. To access it, go to **Build > Pipeline editor** and select the **Lint** tab. +you can use the CI lint tool: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Build > Pipeline editor**. +1. Select the **Lint** tab. This tool checks for syntax and logical errors but goes into more detail than the automatic [validation](#validate-ci-configuration) in the editor. diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index a6b2774dbde..699136ccf97 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compute quota **(PREMIUM ALL)** @@ -53,15 +52,14 @@ By default, GitLab instances do not have a compute quota. The default value for the quota is `0`, which is unlimited. However, you can change this default value. -Prerequisite: +Prerequisites: - You must be a GitLab administrator. To change the default quota that applies to all namespaces: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. In the **Compute quota** box, enter a limit. 1. Select **Save changes**. @@ -75,15 +73,14 @@ If a quota is already defined for a specific namespace, this value does not chan You can override the global value and set a compute quota for a specific namespace. -Prerequisite: +Prerequisites: - You must be a GitLab administrator. To set a compute quota for a namespace: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Groups**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Groups**. 1. For the group you want to update, select **Edit**. 1. In the **Compute quota** box, enter the maximum number of compute minutes. 1. Select **Save changes**. @@ -97,7 +94,7 @@ If you set a quota for a subgroup, it is not used. ## View compute usage -Prerequisite: +Prerequisites: - You must have access to the build to view the total usage and quota summary for a namespace associated with a build. - Access to **Usage Quotas** page is based on your role in the associated namespace or group. @@ -106,7 +103,7 @@ Prerequisite: > Displaying shared runners duration per project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355666) in GitLab 15.0. -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -125,7 +122,7 @@ subgroups, sorted in descending order of compute usage. > Displaying shared runners duration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345795) in GitLab 15.0. -Prerequisite: +Prerequisites: - The namespace must be your personal namespace. @@ -164,7 +161,7 @@ You can find pricing for additional compute minutes on the ### Purchase compute minutes for a group **(FREE SAAS)** -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -183,7 +180,7 @@ namespace. ### Purchase compute minutes for a personal namespace **(FREE SAAS)** -Prerequisite: +Prerequisites: - The namespace must be your personal namespace. diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 21ed66ef939..61862a20436 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Downstream pipelines **(FREE ALL)** @@ -671,9 +671,7 @@ the ones defined in the upstream project take precedence. ### Pass dotenv variables created in a job **(PREMIUM ALL)** -You can pass variables to a downstream job with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) -and [`needs:project`](../yaml/index.md#needsproject). These variables are only available in -the script of the job and can't be used to configure it, for example with `rules` or `artifact:paths`. +You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job). For example, in a [multi-project pipeline](#multi-project-pipelines): diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index f0f0f6d29d2..957e0e0de27 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD pipelines **(FREE ALL)** @@ -126,7 +125,7 @@ you can filter the pipeline list by: pipeline column to display the pipeline ID or the pipeline IID. If you use VS Code to edit your GitLab CI/CD configuration, the -[GitLab Workflow VS Code extension](../../user/project/repository/vscode.md) helps you +[GitLab Workflow VS Code extension](../../editor_extensions/visual_studio_code/index.md) helps you [validate your configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration) and [view your pipeline status](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). @@ -263,18 +262,11 @@ In the example below, the `production` stage has a job with a manual action:  -#### Start multiple manual actions in a stage +#### Start all manual jobs in a stage -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11. - -Multiple manual actions in a single stage can be started at the same time using the "Play all manual" -After you select this action, each individual manual action is triggered and refreshed -to an updated status. - -This functionality is only available: - -- For users with at least the Developer role. -- If the stage contains [manual actions](#add-manual-interaction-to-your-pipeline). +If a stage contains only manual jobs, you can start all the jobs at the same time +by selecting **Play all manual** (**{play}**) above the stage. If the stage contains +non-manual jobs, the option is not displayed. ### Skip a pipeline diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index fb1c19d8770..0de55d2a488 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -39,19 +39,20 @@ Both of these types of pipelines can appear on the **Pipelines** tab of a merge ## Types of merge request pipelines +> - The `detached` label was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352939) to `merge request` in GitLab 14.9. +> - The `merged results` label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132975) in GitLab 16.5. + The three types of merge request pipelines are: - Merge request pipelines, which run on the changes in the merge request's - source branch. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352939) - in GitLab 14.9, these pipelines display a `merge request` label to indicate that the - pipeline ran only on the contents of the source branch, ignoring the target branch. - In GitLab 14.8 and earlier, the label is `detached`. + source branch, ignoring the target branch. These pipelines display a `merge request` label in pipeline lists. - [Merged results pipelines](merged_results_pipelines.md), which run on the result of combining the source branch's changes with the target branch. + These pipelines display a `merged results` label in pipeline lists. - [Merge trains](merge_trains.md), which run when merging multiple merge requests at the same time. The changes from each merge request are combined into the target branch with the changes in the earlier enqueued merge requests, to ensure - they all work together. + they all work together. These pipelines display a `merge train` label in pipeline lists. ## Prerequisites @@ -136,7 +137,7 @@ Pipelines for forks display with the **fork** badge in the parent project:  -### Run pipelines in the parent project **(PREMIUM ALL)** +### Run pipelines in the parent project Project members in the parent project can trigger a merge request pipeline for a merge request submitted from a fork project. This pipeline: diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index a54087262e7..45d9e548d6a 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge trains **(PREMIUM ALL)** @@ -162,13 +162,15 @@ When you remove a merge request from a merge train: ## Skip the merge train and merge immediately If you have a high-priority merge request, like a critical patch that must -be merged urgently, select **Merge Immediately**. +be merged urgently, you can select **Merge Immediately**. When you merge a merge request immediately: -- The current merge train is recreated. -- All pipelines restart. -- Redundant pipelines [are cancelled](#automatic-pipeline-cancellation). +- The commits from the merge request are merged, ignoring the status of the merge train. +- The merge train pipelines for all other merge requests on the train [are cancelled](#automatic-pipeline-cancellation). +- A new merge train starts and all the merge requests from the original merge train are added to this new merge train, + with a new merge train pipeline for each. These new merge train pipelines now contain + the commits added by the merge request that was merged immediately. WARNING: Merging immediately can use a lot of CI/CD resources. Use this option diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index afe7a450370..213a07f49c4 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merged results pipelines **(PREMIUM ALL)** @@ -32,8 +32,6 @@ 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/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/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 305e48ca9f5..9ca2bf26e59 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline architecture **(FREE ALL)** diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 3d24be0f8e1..4a548c8c0af 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline efficiency **(FREE ALL)** @@ -19,7 +18,7 @@ and improve their configuration over time through trial and error. A better proc to use pipeline features that improve efficiency right away, and get a faster software development lifecycle earlier. -First ensure you are familiar with [GitLab CI/CD fundamentals](../introduction/index.md) +First ensure you are familiar with [GitLab CI/CD fundamentals](../index.md) and understand the [quick start guide](../quick_start/index.md). ## Identify bottlenecks and common failures diff --git a/doc/ci/pipelines/pipeline_security.md b/doc/ci/pipelines/pipeline_security.md index d499da21b88..cecc1789946 100644 --- a/doc/ci/pipelines/pipeline_security.md +++ b/doc/ci/pipelines/pipeline_security.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline security diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 1003c03bebf..f83868952f5 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scheduled pipelines **(FREE ALL)** @@ -61,7 +60,7 @@ To trigger a pipeline schedule manually, so that it runs immediately instead of the next scheduled time: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipeline schedules**. +1. Select **Build > Pipeline schedules**. 1. On the right of the list, for the pipeline you want to run, select **Play** (**{play}**). @@ -80,7 +79,7 @@ including [protected environments](../environments/protected_environments.md) an To take ownership of a pipeline created by a different user: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipeline schedules**. +1. Select **Build > Pipeline schedules**. 1. On the right of the list, for the pipeline you want to become owner of, select **Take ownership**. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 321eae183eb..09bfe3ac195 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize pipeline configuration **(FREE ALL)** @@ -103,19 +102,37 @@ To avoid this scenario: For more information, see [Deployment safety](../environments/deployment_safety.md#prevent-outdated-deployment-jobs). +## Restrict roles that can cancel pipelines or jobs **(PREMIUM ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137301) in GitLab 16.7. + +You can customize which roles have permission to cancel pipelines or jobs. + +By default, users with at least the Developer role can cancel pipelines or jobs. +You can restrict cancellation permission to only users with at least the Maintainer role, +or completely prevent cancellation of any pipelines or jobs. + +To change the permissions to cancel pipelines or jobs: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. Select an option from **Minimum role required to cancel a pipeline or job**. +1. Select **Save changes**. + ## Specify a custom CI/CD configuration file > Support for external `.gitlab-ci.yml` locations [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14376) in GitLab 12.6. GitLab expects to find the CI/CD configuration file (`.gitlab-ci.yml`) in the project's root -directory. However, you can specify an alternate filename path, including locations outside the project. +directory. However, you can specify an alternate file name path, including locations outside the project. To customize the path: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. -1. In the **CI/CD configuration file** field, enter the filename. If the file: +1. In the **CI/CD configuration file** field, enter the file name. If the file: - Is not in the root directory, include the path. - Is in a different project, include the group and project name. - Is on an external site, enter the full URL. @@ -208,7 +225,7 @@ You can define how long a job can run before it times out. Jobs that exceed the timeout are marked as failed. -You can override this value [for individual runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +You can override this value [for individual runners](../runners/configure_runners.md#set-the-maximum-job-timeout). ## Pipeline badges diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 1f8c33a9700..3da4e5ad023 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create and run your first GitLab CI/CD pipeline **(FREE ALL)** diff --git a/doc/ci/quick_start/tutorial.md b/doc/ci/quick_start/tutorial.md index 41239615590..389309538e9 100644 --- a/doc/ci/quick_start/tutorial.md +++ b/doc/ci/quick_start/tutorial.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create a complex pipeline diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md index bf41d325ac2..b7b9c216b14 100644 --- a/doc/ci/resource_groups/index.md +++ b/doc/ci/resource_groups/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Control the job concurrency in GitLab CI/CD --- @@ -259,33 +259,40 @@ Sometimes, a job hangs with the message `Waiting for resource: <resource_group>` first check that the resource group is working correctly: 1. Go to the job details page. -1. Select **View job currently using resource**. -1. Check the job status: - - If the status is `running` or `pending`, the feature is working correctly. Wait until the job finishes and releases the resource. - - If the status is `created` and the [process mode](#process-modes) is either **Oldest first** or **Newest first**, the feature is working correctly. +1. If the resource is assigned to a job, select **View job currently using resource** and check the job status. + + - If the status is `running` or `pending`, the feature is working correctly. Wait until the job finishes and releases the resource. + - If the status is `created` and the [process mode](#process-modes) is either **Oldest first** or **Newest first**, the feature is working correctly. Visit the pipeline page of the job and check which upstream stage or job is blocking the execution. - - If none of the above conditions are met, the feature might not be working correctly. - [Open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) with the following information: - - The job ID. - - The job status. - - How often the problem occurs. - - Steps to reproduce the problem. + - If none of the above conditions are met, the feature might not be working correctly. [Report the issue to GitLab](#report-an-issue). + +1. If **View job currently using resource** is not available, the resource is not assigned to a job. Instead, check the resource's upcoming jobs. + + 1. Get the resource's upcoming jobs with the [REST API](../../api/resource_groups.md#list-upcoming-jobs-for-a-specific-resource-group). + 1. Verify that the job's [process mode](#process-modes) is **Oldest first**. + 1. Find the first job in the list of upcoming jobs, and get the job details [with GraphQL](#get-job-details-through-graphql). + 1. If the first job's pipeline is an older pipeline, try to cancel the pipeline or the job itself. + 1. Optional. Repeat this process if the next upcoming job is still in an older pipeline that should no longer run. + 1. If the problem persists, [report the issue to GitLab](#report-an-issue). + +#### Get job details through GraphQL -You can also get job information from the GraphQL API. You should use the GraphQL API if you use [pipeline-level concurrency control with cross-project/parent-child pipelines](#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines) because the trigger jobs are not accessible from the UI. +You can get job information from the GraphQL API. You should use the GraphQL API if you use [pipeline-level concurrency control with cross-project/parent-child pipelines](#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines) because the trigger jobs are not accessible from the UI. To get job information from the GraphQL API: 1. Go to the pipeline details page. 1. Select the **Jobs** tab and find the ID of the stuck job. -1. Go to [GraphiQL explorer](../../api/graphql/index.md#graphiql). +1. Go to the [interactive GraphQL explorer](../../api/graphql/index.md#interactive-graphql-explorer). 1. Run the following query: ```graphql { project(fullPath: "<fullpath-to-your-project>") { name - job(id: "gid://gitlab/Ci::Bridge/<job-id>") { + job(id: "gid://gitlab/Ci::Build/<job-id>") { name + status detailedStatus { action { path @@ -305,7 +312,7 @@ To get job information from the GraphQL API: { project(fullPath: "<fullpath-to-your-project>") { name - job(id: "gid://gitlab/Ci::Bridge/<job-id-currently-using-the-resource>") { + job(id: "gid://gitlab/Ci::Build/<job-id-currently-using-the-resource>") { name status pipeline { @@ -316,4 +323,13 @@ To get job information from the GraphQL API: } ``` - If the status is not `running` or `pending`, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and [contact support](https://about.gitlab.com/support/#contact-support) so they can apply the correct labels to the issue. +### Report an issue + +[Open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) with the following information: + +- The ID of the affected job. +- The job status. +- How often the problem occurs. +- Steps to reproduce the problem. + + You can also [contact support](https://about.gitlab.com/support/#contact-support) for further assistance, or to get in touch with the development team. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index f831c53c024..3ff25cc8bab 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review apps **(FREE ALL)** @@ -70,7 +70,7 @@ as mentioned above. To facilitate this, and if you are using Kubernetes, you can **Enable review apps** and GitLab prompts you with a template code block that you can copy and paste into `.gitlab-ci.yml` as a starting point. -Prerequisite: +Prerequisites: - You need at least the Developer role for the project. diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index bca0b50563a..3b21d865d8b 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring runners **(FREE ALL)** @@ -11,53 +11,79 @@ If you have installed your own runners, you can configure and secure them in Git If you need to configure runners on the machine where you installed GitLab Runner, see [the GitLab Runner documentation](https://docs.gitlab.com/runner/configuration/). -## Manually clear the runner cache +## Set the maximum job timeout -Read [clearing the cache](../caching/index.md#clearing-the-cache). +You can specify a maximum job timeout for each runner to prevent projects +with longer job timeouts from using the runner. The maximum job timeout is +used of it is shorter than the job timeout defined in the project. -## Set maximum job timeout for a runner +### For a shared runner -For each runner, you can specify a *maximum job timeout*. This timeout, -if smaller than the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run), takes precedence. +Prerequisites: + +- You must be an administrator. + +On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) instead. + +To set the maximum job timeout: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner, you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). +1. Select **Save changes**. + +### For a group runner + +Prerequisites: + +- You must have the Owner role for the group. -This feature can be used to prevent your shared runner from being overwhelmed -by a project that has jobs with a long timeout (for example, one week). +To set the maximum job timeout: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). +1. Select **Save changes**. -On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +### For a project runner + +Prerequisites: + +- You must have the Owner role for the project. To set the maximum job timeout: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. -1. Select your project runner to edit the settings. -1. Enter a value under **Maximum job timeout**. Must be 10 minutes or more. If not - defined, the [project's job timeout setting](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) - is used. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). If not defined, the [job timeout for the project](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) is used instead. 1. Select **Save changes**. -How this feature works: +## How maximum job timeout works **Example 1 - Runner timeout bigger than project timeout** -1. You set the _maximum job timeout_ for a runner to 24 hours -1. You set the _CI/CD Timeout_ for a project to **2 hours** -1. You start a job -1. The job, if running longer, times out after **2 hours** +1. You set the _maximum job timeout_ for a runner to 24 hours. +1. You set the _CI/CD Timeout_ for a project to **2 hours**. +1. You start a job. +1. The job, if running longer, times out after **2 hours**. **Example 2 - Runner timeout not configured** -1. You remove the _maximum job timeout_ configuration from a runner -1. You set the _CI/CD Timeout_ for a project to **2 hours** -1. You start a job -1. The job, if running longer, times out after **2 hours** +1. You remove the _maximum job timeout_ configuration from a runner. +1. You set the _CI/CD Timeout_ for a project to **2 hours**. +1. You start a job. +1. The job, if running longer, times out after **2 hours**. **Example 3 - Runner timeout smaller than project timeout** -1. You set the _maximum job timeout_ for a runner to **30 minutes** -1. You set the _CI/CD Timeout_ for a project to 2 hours -1. You start a job -1. The job, if running longer, times out after **30 minutes** +1. You set the _maximum job timeout_ for a runner to **30 minutes**. +1. You set the _CI/CD Timeout_ for a project to 2 hours. +1. You start a job. +1. The job, if running longer, times out after **30 minutes**. ## Set `script` and `after_script` timeouts @@ -66,7 +92,7 @@ How this feature works: To control the amount of time `script` and `after_script` runs before it terminates, you can set specify a timeout. For example, you can specify a timeout to terminate a long-running `script` early, so that artifacts and caches can still be uploaded -before the [job timeout](#set-maximum-job-timeout-for-a-runner) is exceeded. +before the job timeout is exceeded. - To set a timeout for `script`, use the job variable `RUNNER_SCRIPT_TIMEOUT`. - To set a timeout for `after_script`, and override the default of 5 minutes, use the job variable `RUNNER_AFTER_SCRIPT_TIMEOUT`. @@ -105,26 +131,11 @@ of shared runners on large GitLab instances. This ensures that you control access to your GitLab instances and secure [runner executors](https://docs.gitlab.com/runner/executors/). If certain executors run a job, the file system, the code the runner executes, -and the runner authentication token may be exposed. This means that anyone that runs jobs +and the runner authentication token may be exposed. This means that anyone who runs jobs on a _shared runner_ can access another user's code that runs on the runner. Users with access to the runner authentication token can use it to create a clone of a runner and submit false jobs in a vector attack. For more information, see [Security Considerations](https://docs.gitlab.com/runner/security/). -### Prevent runners from revealing sensitive information - -To ensure runners don't reveal sensitive information, you can configure them to only run jobs -on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). - -To prevent runners from revealing sensitive information: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > CI/CD**. -1. Expand **Runners**. -1. Find the runner you want to protect or unprotect. Make sure the runner is enabled. -1. Select **Edit** (**{pencil}**). -1. Select the **Protected** checkbox. -1. Select **Save changes**. - ### Using shared runners in forked projects When a project is forked, the job settings related to jobs are copied. If you have shared runners @@ -163,6 +174,23 @@ After you reset the registration token, it is no longer valid and does not regis any new runners to the project. You should also update the registration token in tools you use to provision and register new values. +## 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. +> - [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 [runner authentication token](../../api/runners.md#registration-and-authentication-tokens) +to connect with the GitLab instance. + +To help prevent the token from being compromised, you can have the +token rotate automatically at specified intervals. When the tokens are rotated, +they are updated for each runner, regardless of the runner's status (`online` or `offline`). + +No manual intervention should be required, and no running jobs should be affected. + +If you need to manually update the runner authentication token, you can run a +command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token). + ### Reset the runner authentication token If a runner authentication token is revealed, an attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). @@ -179,37 +207,131 @@ To reset the runner authentication token: - [Create a project runner](runners_scope.md#create-a-project-runner-with-a-runner-authentication-token). 1. Optional. To verify that the previous runner authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). -## Use tags to control which jobs a runner can run +### Automatically rotate runner authentication tokens + +You can specify an interval for runner authentication tokens to rotate. +This rotation helps ensure the security of the tokens assigned to your runners. + +Prerequisites: + +- Runners must use [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions). +- You must be an administrator. + +To automatically rotate runner authentication tokens: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. Set a **Runners expiration** time for runners, leave empty for no expiration. +1. Select **Save changes**. + +Before the interval expires, runners automatically request a new runner authentication token. + +## Prevent runners from revealing sensitive information + +To ensure runners don't reveal sensitive information, you can configure them to only run jobs +on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). + +Runners configured to run jobs on protected branches cannot run jobs in [merge request pipelines](../pipelines/merge_request_pipelines.md). + +### For a shared runner + +Prerequisites: + +- You must be an administrator. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +### For a group runner + +Prerequisites: + +- You must have the Owner role for the group. + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +### For a project runner + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +## Control jobs that a runner can run -You can use [tags](../yaml/index.md#tags) to ensure that runners only run the jobs they are equipped -to run. For example, you can specify the `rails` tag for runners that have the dependencies to run +You can use [tags](../yaml/index.md#tags) to control the jobs a runner can run. +For example, you can specify the `rails` tag for runners that have the dependencies to run Rails test suites. GitLab CI/CD tags are different to Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. -### Set a runner to run untagged jobs +### For a shared runner + +Prerequisites: + +- You must be an administrator. + +To set the maximum job timeout: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `rails`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. +1. Select **Save changes**. + +### For a group runner -When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** -[tagged jobs](../yaml/index.md#tags). -To change this, you must have the Owner role for the project. +Prerequisites: + +- You must have the Owner role for the group. + +To set the maximum job timeout: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. +1. Select **Save changes**. + +### For a project runner + +Prerequisites: -To make a runner pick untagged jobs: +- You must have the Owner role for the project. + +To set a runner to run tagged jobs: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. -1. Find the runner you want to pick untagged jobs and make sure it's enabled. -1. Select **Edit** (**{pencil}**). -1. Select the **Run untagged jobs** checkbox. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. 1. Select **Save changes**. -NOTE: -The runner tags list cannot be empty when it's not allowed to pick untagged jobs. - -Below are some example scenarios of different variations. +### How the runner uses tags -### Runner runs only tagged jobs +#### Runner runs only tagged jobs The following examples illustrate the potential impact of the runner being set to run only tagged jobs. @@ -229,7 +351,7 @@ Example 3: 1. The runner is configured to run only tagged jobs and has the `docker` tag. 1. A job that has no tags defined is executed and stuck. -### Runner is allowed to run untagged jobs +#### Runner is allowed to run untagged jobs The following examples illustrate the potential impact of the runner being set to run tagged and untagged jobs. @@ -246,7 +368,7 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. -### A runner and a job have multiple tags +#### A runner and a job have multiple tags The selection logic that matches the job and runner is based on the list of `tags` defined in the job. @@ -273,7 +395,9 @@ Example 3: You can use tags to run different jobs on different platforms. For example, if you have an OS X runner with tag `osx` and a Windows runner with tag -`windows`, you can run a job on each platform: +`windows`, you can run a job on each platform. + +Update the `tags` field in the `config.toml`: ```yaml windows job: @@ -295,7 +419,7 @@ osx job: > Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742). -You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: +In the `.gitlab-ci.yml` file, use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: ```yaml variables: @@ -786,7 +910,7 @@ variables: NOTE: Zip archives are the only supported artifact type. Follow [the issue for details](https://gitlab.com/gitlab-org/gitlab/-/issues/367203). -GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The filename is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../jobs/job_artifacts.md#with-a-dynamically-defined-name) in the CI file. The filename, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. +GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The file name is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../jobs/job_artifacts.md#with-a-dynamically-defined-name) in the CI file. The file name, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. ### Attestation format @@ -795,7 +919,7 @@ The attestation metadata is generated in the [in-toto attestation format](https: | Field | Value | | ------ | ------ | | `_type` | `https://in-toto.io/Statement/v0.1` | -| `subject.name` | The filename of the artifact. | +| `subject.name` | The file name of the artifact. | | `subject.digest.sha256` | The artifact's `sha256` checksum. | | `predicateType` | `https://slsa.dev/provenance/v0.2` | | `predicate.buildType` | `https://gitlab.com/gitlab-org/gitlab-runner/-/blob/{GITLAB_RUNNER_VERSION}/PROVENANCE.md`. For example v15.0.0 | @@ -911,40 +1035,3 @@ setting. `FASTZIP_EXTRACTOR_CONCURRENCY` controls how many files are decompressed at once. Files from a zip archive can natively be read from concurrency, so no additional memory is allocated in addition to what the decompressor requires. This defaults to the number of CPUs available. - -## 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. -> - [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 [runner authentication token](../../api/runners.md#registration-and-authentication-tokens) -to connect with the GitLab instance. - -To help prevent the token from being compromised, you can have the -token rotate automatically at specified intervals. When the tokens are rotated, -they are updated for each runner, regardless of the runner's status (`online` or `offline`). - -No manual intervention should be required, and no running jobs should be affected. - -If you need to manually update the runner authentication token, you can run a -command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token). - -### Automatically rotate runner authentication tokens - -You can specify an interval for runner authentication tokens to rotate. -This rotation helps ensure the security of the tokens assigned to your runners. - -Prerequisites: - -- Ensure your runners are using [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions). - -To automatically rotate runner authentication tokens: - -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment** -1. Set a **Runners expiration** time for runners, leave empty for no expiration. -1. Select **Save**. - -Before the interval expires, runners automatically request a new runner authentication token. diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 7e597264e1e..1df93ed8896 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner SaaS -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runner SaaS **(FREE SAAS)** @@ -21,7 +20,7 @@ For more information about the cost factor applied to the machine type based on The number of minutes you can use on these runners depends on the [maximum number of units of compute](../pipelines/cicd_minutes.md) in your [subscription plan](https://about.gitlab.com/pricing/). -[Untagged](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) jobs automatically run in containers +[Untagged](../../ci/runners/configure_runners.md#control-jobs-that-a-runner-can-run) jobs automatically run in containers on the `small` Linux runners. The objective is to make 90% of CI/CD jobs start executing in 120 seconds or less. The error rate should be less than 0.5%. diff --git a/doc/ci/runners/new_creation_workflow.md b/doc/ci/runners/new_creation_workflow.md index 022f7af11ec..c870a89a77a 100644 --- a/doc/ci/runners/new_creation_workflow.md +++ b/doc/ci/runners/new_creation_workflow.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating to the new runner registration workflow **(FREE ALL)** @@ -29,7 +29,7 @@ you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab For the new runner registration workflow, you: -1. [Create a runner](register_runner.md) directly in the GitLab UI. +1. [Create a runner](runners_scope.md) directly in the GitLab UI. 1. Receive a runner authentication token. 1. Use the runner authentication token instead of the registration token when you register a runner with this configuration. Runner managers registered in multiple hosts appear @@ -141,7 +141,7 @@ process is started. ## Creating runners programmatically -In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner) +In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner as an authenticated user. This should only be used if the runner configuration is dynamic or not reusable. If the runner configuration is static, you should reuse the runner authentication token of an existing runner. diff --git a/doc/ci/runners/register_runner.md b/doc/ci/runners/register_runner.md deleted file mode 100644 index bca11682258..00000000000 --- a/doc/ci/runners/register_runner.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'runners_scope.md' -remove_date: '2023-09-21' ---- - -This document was moved to [another location](runners_scope.md). - -<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> -<!-- 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/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 6b6493db2c4..48f6a22e9b3 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage runners **(FREE ALL)** @@ -40,7 +39,7 @@ If you are using GitLab.com: > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. -Prerequisite: +Prerequisites: - You must be an administrator. @@ -48,9 +47,8 @@ When you create a runner, it is assigned a runner authentication token that you To create a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Select **New instance runner**. 1. Select the operating system where GitLab Runner is installed. 1. In the **Tags** section, in the **Tags** field, enter the job tags to specify jobs the runner can run. @@ -65,7 +63,7 @@ To create a shared runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for a limited period of time during registration. After you register the runner, @@ -78,14 +76,13 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisite: +Prerequisites: - You must be an administrator. To create a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Select **Register an instance runner**. 1. Copy the registration token. @@ -93,14 +90,13 @@ To create a shared runner: ### Pause or resume a shared runner -Prerequisite: +Prerequisites: - You must be an administrator. You can pause a runner so that it does not accept jobs from groups and projects in the GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the runner list. 1. In the runner list, to the right of the runner: @@ -109,7 +105,7 @@ You can pause a runner so that it does not accept jobs from groups and projects ### Delete shared runners -Prerequisite: +Prerequisites: - You must be an administrator. @@ -119,8 +115,7 @@ jobs, you can [pause](#pause-or-resume-a-shared-runner) the runner instead. To delete a single or multiple shared runners: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the list of runners. 1. Delete the shared runner: @@ -263,7 +258,7 @@ To create a group runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for only a short period of time during registration. @@ -295,7 +290,7 @@ how to [register a runner](https://docs.gitlab.com/runner/register/#register-wit > Ability for users with the Maintainer role to view group runners [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384179) in GitLab 16.4. -Prerequisite: +Prerequisites: - You must have the Maintainer or Owner role for the group. @@ -324,7 +319,7 @@ those in other groups: ### Pause or resume a group runner -Prerequisite: +Prerequisites: - You must be an administrator or have the Owner role for the group. @@ -342,7 +337,7 @@ instance. If you pause a group runner that is used by multiple projects, the run > Multiple runner deletion [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6. -Prerequisite: +Prerequisites: - You must be an administrator or have the Owner role for the group. @@ -365,7 +360,7 @@ To delete a single or multiple group runners: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1. -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -457,7 +452,7 @@ To create a project runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for only a short period of time during registration. @@ -469,7 +464,7 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -487,7 +482,7 @@ The runner is now enabled for the project. ### Pause or resume a project runner -Prerequisite: +Prerequisites: - You must be an administrator, or have the Maintainer role for the project. @@ -588,9 +583,8 @@ runners are considered. queued for longer than the median value, and half of the jobs queued for less than the median value. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Select **View metrics**. ## Determine which runners need to be upgraded **(ULTIMATE ALL)** @@ -607,8 +601,7 @@ To determine which runners need to be upgraded: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. - For the instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Above the list of runners, view the status: @@ -631,15 +624,14 @@ different places. ### Determine the IP address of a shared runner -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To determine the IP address of a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Find the runner in the table and view the **IP Address** column.  diff --git a/doc/ci/runners/saas/gpu_saas_runner.md b/doc/ci/runners/saas/gpu_saas_runner.md index 6dc9d8c9534..e9313c65f11 100644 --- a/doc/ci/runners/saas/gpu_saas_runner.md +++ b/doc/ci/runners/saas/gpu_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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GPU-enabled SaaS runners **(PREMIUM SAAS)** diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index 23a9b26a8d7..2534db79795 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Linux **(FREE SAAS)** diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index b503fea4f2f..03c23680c1c 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on macOS **(PREMIUM SAAS BETA)** @@ -36,11 +36,11 @@ GitLab SaaS provides a set of VM images for macOS. You can execute your build in one of the following images, which you specify in your `.gitlab-ci.yml` file. Each image runs a specific version of macOS and Xcode. -| VM image | Status | -|----------------------------|--------| -| `macos-12-xcode-14` | `GA` | -| `macos-13-xcode-14` | `GA` | -| `macos-14-xcode-15` | `Beta` | +| VM image | Status | | +|----------------------------|--------|--------------| +| `macos-12-xcode-14` | `GA` | | +| `macos-13-xcode-14` | `GA` | [Preinstalled Software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/blob/main/toolchain/macos-13.yml) | +| `macos-14-xcode-15` | `Beta` | [Preinstalled Software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/blob/main/toolchain/macos-14.yml) | If no image is specified, the macOS runner uses `macos-13-xcode-14`. @@ -48,7 +48,7 @@ If no image is specified, the macOS runner uses `macos-13-xcode-14`. macOS and Xcode follow a yearly release cadence, during which GitLab increments its versions synchronously. GitLab typically supports multiple versions of preinstalled tools. For more information, see the [full list of preinstalled software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/tree/main/toolchain). -When Apple releases a new macOS version, GitLab releases a new `stable` image based on the OS in the next release, +When Apple releases a new macOS version, GitLab releases a new `stable` image based on the OS in the next release, which is in Beta. With the release of the first patch to macOS, the `stable` image becomes Generally Available (GA). As only two GA images are supported at a time, the prior OS version becomes deprecated and is deleted after three months in accordance with the [supported image lifecycle](../index.md#supported-image-lifecycle). diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index 108388f22c8..fd1d5ba1ab7 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Windows **(FREE SAAS BETA)** diff --git a/doc/ci/secrets/azure_key_vault.md b/doc/ci/secrets/azure_key_vault.md index d8a511e8bdf..6eefd0da74c 100644 --- a/doc/ci/secrets/azure_key_vault.md +++ b/doc/ci/secrets/azure_key_vault.md @@ -1,16 +1,13 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Azure Key Vault secrets in GitLab CI/CD **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. - -NOTE: -A [bug was discovered](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) and this feature might not work as expected or at all. A fix is scheduled for a future release. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. Due to [issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) this feature did not work as expected. +> - [Issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) resolved and this feature made generally available in GitLab Runner 16.6. You can use secrets stored in the [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/) in your GitLab CI/CD pipelines. @@ -69,8 +66,8 @@ RESPONSE 400 Bad Request AADSTS50027: JWT token is invalid or malformed. ``` -This occurs due to a known issue in GitLab Runner where the JWT token isn't parsed correctly. -A fix is [scheduled for a future GitLab Runner release](https://gitlab.com/gitlab-org/gitlab/-/issues/424746). +This occurs due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) in GitLab Runner where the JWT token isn't parsed correctly. +To resolve this, upgrade to GitLab Runner 16.6 or later. ### `Caller is not authorized to perform action on resource` message @@ -83,7 +80,7 @@ Caller is not authorized to perform action on resource.\r\nIf role assignments, ForbiddenByRbac ``` -If your Azure Key Vault is using RBAC, you must add the **Key Vault Secrets User** to your Azure AD +If your Azure Key Vault is using RBAC, you must add the **Key Vault Secrets User** role assignment to your Azure AD application. For example: diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md index 20eae01f45b..80d1a1febd2 100644 --- a/doc/ci/secrets/convert-to-id-tokens.md +++ b/doc/ci/secrets/convert-to-id-tokens.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM ALL)** diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md index 325972e06c2..1b3a6b837a5 100644 --- a/doc/ci/secrets/id_token_authentication.md +++ b/doc/ci/secrets/id_token_authentication.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OpenID Connect (OIDC) Authentication Using ID Tokens **(FREE ALL)** diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index e663d8d5c14..e452b26d8a9 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using external secrets in CI **(FREE ALL)** diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index d2ce98ad048..ee074c2a99c 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level Secure Files **(FREE ALL)** @@ -61,3 +60,26 @@ WARNING: The content of files loaded with the `download-secure-files` tool are not [masked](../variables/index.md#mask-a-cicd-variable) in the job log output. Make sure to avoid outputting secure file contents in the job log, especially when logging output that could contain sensitive information. + +## Security details + +Project-level Secure Files are encrypted on upload using the [Lockbox](https://github.com/ankane/lockbox) +Ruby gem by using the [`Ci::SecureFileUploader`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/uploaders/ci/secure_file_uploader.rb) +interface. This interface generates a SHA256 checksum of the source file during upload +that is persisted with the record in the database so it can be used to verify the contents +of the file when downloaded. + +A [unique encryption key](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/secure_file.rb#L27) +is generated for each file when it is created and persisted in the database. The encrypted uploaded files +are stored in either local storage or object storage depending on the [GitLab instance configuration](../../administration/secure_files.md). + +Individual files can be retrieved with the [secure files download API](../../api/secure_files.md#download-secure-file). +Metadata can be retrieved with the [list](../../api/secure_files.md#list-project-secure-files) +or [show](../../api/secure_files.md#show-secure-file-details) API endpoints. Files can also be retrieved +with the [`download-secure-files`](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files) +tool. This tool automatically verifies the checksum of each file as it is downloaded. + +Any project member with at least the Developer role can access Project-level secure files. +Interactions with Project-level secure files are not included in Audit Events, but +[issue 117](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/readme/-/issues/117). +proposes adding this functionality. diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 54fc664ef12..94fba9cff98 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab as a microservice **(FREE ALL)** diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index d0481482d00..9a624f88339 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Services **(FREE ALL)** @@ -27,7 +26,7 @@ than to install `mysql`, for example, every time the project is built. You're not limited to only database services. You can add as many services you need to `.gitlab-ci.yml` or manually modify the [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). -Any image found at [Docker Hub](https://hub.docker.com/) or your private Container Registry can be +Any image found at [Docker Hub](https://hub.docker.com/) or your private container registry can be used as a service. Services inherit the same DNS servers, search domains, and additional hosts as @@ -436,54 +435,48 @@ See [Mask a CI/CD Variable](../variables/index.md#mask-a-cicd-variable) ## Debug a job locally -The following commands are run without root privileges. You should be -able to run Docker with your user account. +The following commands are run without root privileges. You should be able to run Docker with your user account. -First start with creating a file named `build_script`: +First start by creating a file named `build_script`: ```shell cat <<EOF > build_script git clone https://gitlab.com/gitlab-org/gitlab-runner.git /builds/gitlab-org/gitlab-runner cd /builds/gitlab-org/gitlab-runner -make +make runner-bin-host EOF ``` -Here we use as an example the GitLab Runner repository which contains a -Makefile, so running `make` executes the commands defined in the Makefile. -Instead of `make`, you could run the command which is specific to your project. +Here we use as an example the GitLab Runner repository which contains a Makefile, so running `make` executes the target +defined in the Makefile. Instead of `make runner-bin-host`, you could run the command which is specific to your project. -Then create some service containers: +Then create a service container: ```shell -docker run -d --name service-mysql mysql:latest -docker run -d --name service-postgres postgres:latest +docker run -d --name service-redis redis:latest ``` -The previous commands create two service containers. The service container named `service-mysql` uses the latest MySQL image. The one named `service-postgres` uses the latest PostgreSQL image. Both service containers run in the background (`-d`). +The previous command creates a service container named `service-redis` using the latest Redis image. The service +container runs in the background (`-d`). -Finally, create a build container by executing the `build_script` file we -created earlier: +Finally, create a build container by executing the `build_script` file we created earlier: ```shell -docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.6 /bin/bash < build_script +docker run --name build -i --link=service-redis:redis golang:latest /bin/bash < build_script ``` -The above command creates a container named `build` that's spawned from -the `ruby:2.6` image and has two services linked to it. The `build_script` is -piped using `stdin` to the bash interpreter which in turn executes the +The above command creates a container named `build` that is spawned from the `golang:latest` image and has one service +linked to it. The `build_script` is piped using `stdin` to the bash interpreter which in turn executes the `build_script` in the `build` container. -When you finish testing and no longer need the containers, you can remove them -with: +When you finish testing and no longer need the containers, you can remove them with: ```shell -docker rm -f -v build service-mysql service-postgres +docker rm -f -v build service-redis ``` -This forcefully (`-f`) removes the `build` container, the two service -containers, and all volumes (`-v`) that were created with the container -creation. +This forcefully (`-f`) removes the `build` container, the service container, and all volumes (`-v`) that were created +with the container creation. ## Security when using services containers diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index d02df1faf55..a5a87c2a199 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using MySQL **(FREE ALL)** diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index b491786b4a1..7a3ad0ee804 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using PostgreSQL **(FREE ALL)** diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index d86ffdfabd6..94c0603f31f 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Redis **(FREE ALL)** diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index ad45345fa38..b848f436e34 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using SSH keys with GitLab CI/CD **(FREE ALL)** @@ -25,12 +24,15 @@ environment by extending your `.gitlab-ci.yml`, and it's a solution that works with any type of [executor](https://docs.gitlab.com/runner/executors/) (like Docker or shell, for example). -## How it works +## Create and use an SSH key + +To create and use an SSH key in GitLab CI/CD: 1. Create a new SSH key pair locally with [`ssh-keygen`](https://linux.die.net/man/1/ssh-keygen) -1. Add the private key as a [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) to - your project -1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load +1. Add the private key as a [file type CI/CD variable](../variables/index.md#for-a-project) to + your project. The variable value must end in a newline (`LF` character). To add a newline, press <kbd>Enter</kbd> or <kbd>Return</kbd> + at the end of the last line of the SSH key before saving it in the CI/CD settings. +1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) in the job, which loads the private key. 1. Copy the public key to the servers you want to have access to (usually in `~/.ssh/authorized_keys`) or add it as a [deploy key](../../user/project/deploy_keys/index.md) @@ -52,9 +54,11 @@ to access it. In this case, you can use an SSH key pair. **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. -1. Create a new [file type CI/CD variable](../variables/index.md). - As **Key** enter the name `SSH_PRIVATE_KEY` and in the **Value** field paste - the content of your _private_ key that you created earlier. +1. Create a new [file type CI/CD variable](../variables/index.md#for-a-project). + - In the **Key** field, enter `SSH_PRIVATE_KEY`. + - In the **Value** field, paste the content of your _private_ key from the key pair that you created earlier. + Make sure the file ends with a newline. To add a newline, press + <kbd>Enter</kbd> or <kbd>Return</kbd> at the end of the last line of the SSH key before saving your changes. 1. Modify your `.gitlab-ci.yml` with a `before_script` action. In the following example, a Debian based image is assumed. Edit to your needs: @@ -161,6 +165,8 @@ ssh-keyscan 10.0.2.2 Create a new [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) with `SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. +Make sure the file ends with a newline. To add a newline, press <kbd>Enter</kbd> or <kbd>Return</kbd> +at the end of the last line of the SSH key before saving your changes. If you must connect to multiple servers, all the server host keys must be collected in the **Value** of the variable, one key per line. @@ -202,11 +208,19 @@ before_script: # - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config' ``` -## Example project +## Use SSH key without a file type CI/CD variable + +If you do not want to use a file type CI/CD variable, the [example SSH Project](https://gitlab.com/gitlab-examples/ssh-private-key/) +shows an alternative method. This method uses a regular CI/CD variable instead of +the file type variable recommended above. + +## Troubleshooting + +### `Error loading key "/builds/path/SSH_PRIVATE_KEY": error in libcrypto` message -We have set up an [Example SSH Project](https://gitlab.com/gitlab-examples/ssh-private-key/) for your convenience -that runs on [GitLab.com](https://gitlab.com) using our publicly available -[shared runners](../runners/index.md). +This message can be returned if there is a formatting error with the SSH key. -Want to hack on it? Fork it, commit, and push your changes. In a few -moments the changes is picked by a public runner and the job starts. +When saving the SSH key as a [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables), +the value must end with a newline (`LF` character). To add a newline, press <kbd>Enter</kbd> or <kbd>Return</kbd> +at the end of the `-----END OPENSSH PRIVATE KEY-----` line of the SSH key before saving +the variable. diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 071884f2bed..56c4c475294 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -1,9 +1,8 @@ --- stage: Plan group: Product Planning -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.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 --- # Test cases **(ULTIMATE ALL)** @@ -21,7 +20,7 @@ For more information, see [Product Stage Direction - Plan](https://about.gitlab. ## Create a test case -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -91,7 +90,7 @@ or editing an existing one. When you want to stop using a test case, you can archive it. You can [reopen an archived test case](#reopen-an-archived-test-case) later. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/ci/testing/accessibility_testing.md b/doc/ci/testing/accessibility_testing.md index 783e787f8a7..f8faaeec8f8 100644 --- a/doc/ci/testing/accessibility_testing.md +++ b/doc/ci/testing/accessibility_testing.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Accessibility testing **(FREE ALL)** diff --git a/doc/ci/testing/browser_performance_testing.md b/doc/ci/testing/browser_performance_testing.md index d8c66c2d4d5..2988cfedce5 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Browser Performance Testing **(PREMIUM ALL)** @@ -49,7 +49,8 @@ If the Browser Performance report has no data to compare, such as when you add t Browser Performance job in your `.gitlab-ci.yml` for the very first time, the Browser Performance report widget doesn't display. It must have run at least once on the target branch (`main`, for example), before it displays in a -merge request targeting that branch. +merge request targeting that branch. Additionally, the widget only displays if the +job ran in the latest pipeline for the Merge request.  @@ -134,11 +135,11 @@ be extended for dynamic environments, but a few extra steps are required: 1. The `browser_performance` job should run after the dynamic environment has started. 1. In the `review` job: - 1. Generate a URL list file with the dynamic URL. - 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` - in your job's `script`. - 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) - to the `browser_performance` job. + 1. Generate a URL list file with the dynamic URL. + 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` + in your job's `script`. + 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) + to the `browser_performance` job. 1. You can now run the sitespeed.io container against the desired hostname and paths. diff --git a/doc/ci/testing/code_coverage.md b/doc/ci/testing/code_coverage.md index a39586a9eb0..43df79c44f5 100644 --- a/doc/ci/testing/code_coverage.md +++ b/doc/ci/testing/code_coverage.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code coverage **(FREE ALL)** @@ -76,7 +76,7 @@ To see the evolution of your project code coverage over time, you can view a graph or download a CSV file with this data. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Analyze > Repository analytics**. +1. Select **Analyze > Repository analytics**. The historic data for each job is listed in the dropdown list above the graph. diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 6b4275d8055..23ae615eeb2 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Quality **(FREE ALL)** @@ -51,7 +51,9 @@ Code Quality results are shown in the: Code Quality analysis results display in the merge request widget area if a report from the target branch is available for comparison. The merge request widget displays Code Quality findings and resolutions that -were introduced by the changes made in the merge request. +were introduced by the changes made in the merge request. Multiple Code Quality findings with identical +fingerprints display as a single entry in the merge request widget, each individual finding is available in the +full report available in the **Pipeline** details view.  @@ -63,9 +65,9 @@ were introduced by the changes made in the merge request. > - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. Code Quality results display in the merge request **Changes** view. Lines containing Code Quality -issues are marked by an indicator beside the gutter. Hover over the marker for details of the issue. +issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details. - + ### Pipeline details view **(PREMIUM ALL)** @@ -350,7 +352,7 @@ the nested method of container execution. 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 + accessible from your job environment. GitLab container registry can be used here to host your own copy. - `CODECLIMATE_PREFIX`: The domain of your intended container image registry. This is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). @@ -420,7 +422,7 @@ code_quality: You can use a Dependency Proxy to reduce the time taken to download dependencies. -Prerequisite: +Prerequisites: - [Dependency Proxy](../../user/packages/dependency_proxy/index.md) enabled in the project's group. @@ -518,15 +520,15 @@ Code Quality functionality can be extended by using Code Climate For example, to use the [SonarJava analyzer](https://docs.codeclimate.com/docs/sonar-java): 1. Add a file named `.codeclimate.yml` to the root of your repository -1. Add to the `.codeclimate.yml` the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin) - for the plugin to the root of your repository: +1. Add the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin) + for the plugin to the root of your repository to the `.codeclimate.yml` file: - ```yaml - version: "2" - plugins: - sonar-java: - enabled: true - ``` + ```yaml + version: "2" + plugins: + sonar-java: + enabled: true + ``` This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) @@ -550,7 +552,7 @@ You should configure Code Quality checks to run on your worker as documented in A common issue is that the terms `Code Quality` (GitLab specific) and `Code Climate` (Engine used by GitLab) are very similar. You must add a **`.codeclimate.yml`** file to change the default configuration, **not** a `.codequality.yml` file. If you use -the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) +the wrong file name, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. ### No Code Quality report is displayed in a merge request @@ -718,7 +720,7 @@ To gain insight into the errors, you can execute a GraphQL query using the follo 1. Go to the pipeline details page. 1. Append `.json` to the URL. 1. Copy the `iid` of the pipeline. -1. Go to [GraphiQL explorer](../../api/graphql/index.md#graphiql). +1. Go to the [interactive GraphQL explorer](../../api/graphql/index.md#interactive-graphql-explorer). 1. Run the following query: ```graphql diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md index d47053fa971..22ce9bb52d8 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fail Fast Testing **(PREMIUM ALL)** diff --git a/doc/ci/testing/img/code_quality_inline_indicator_v16_7.png b/doc/ci/testing/img/code_quality_inline_indicator_v16_7.png Binary files differnew file mode 100644 index 00000000000..0d7d5bb3062 --- /dev/null +++ b/doc/ci/testing/img/code_quality_inline_indicator_v16_7.png diff --git a/doc/ci/testing/img/code_quality_mr_diff_report_v15_7.png b/doc/ci/testing/img/code_quality_mr_diff_report_v15_7.png Binary files differdeleted file mode 100644 index b45124e0e5d..00000000000 --- a/doc/ci/testing/img/code_quality_mr_diff_report_v15_7.png +++ /dev/null diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md index dadbc3821cc..2909bac4d0b 100644 --- a/doc/ci/testing/index.md +++ b/doc/ci/testing/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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test with GitLab CI/CD and generate reports in merge requests **(FREE ALL)** diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md index 6b16f15a9d9..a79136c0083 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Performance Testing **(PREMIUM ALL)** diff --git a/doc/ci/testing/metrics_reports.md b/doc/ci/testing/metrics_reports.md index 0f1eaedfb78..faa7add64b3 100644 --- a/doc/ci/testing/metrics_reports.md +++ b/doc/ci/testing/metrics_reports.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics Reports **(PREMIUM ALL)** diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 56d42a30ca7..ff55f37e1ff 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test coverage visualization **(FREE ALL)** diff --git a/doc/ci/testing/unit_test_report_examples.md b/doc/ci/testing/unit_test_report_examples.md index fb11467cd7d..bade653bf18 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test report examples **(FREE ALL)** diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index b37dd54e96b..59401449b63 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test reports **(FREE ALL)** @@ -94,6 +94,10 @@ To copy the name of a single failed test: If a test failed in the project's default branch in the last 14 days, a message like `Failed {n} time(s) in {default_branch} in the last 14 days` is displayed for that test. +The calculation includes failed tests in completed pipelines, but not [blocked pipelines](../jobs/job_control.md#types-of-manual-jobs). +[Issue 431265](https://gitlab.com/gitlab-org/gitlab/-/issues/431265) proposes to +also include blocked pipelines in the calculation. + ## How to set it up To enable the Unit test reports in merge requests, you must add diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index ee1e05c4fc9..4eee34af402 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Trigger pipelines by using the API **(FREE ALL)** @@ -10,6 +9,10 @@ type: tutorial To trigger a pipeline for a specific branch or tag, you can use an API call to the [pipeline triggers API endpoint](../../api/pipeline_triggers.md). +If you are [migrating to GitLab CI/CD](../migration/plan_a_migration.md), you can +trigger GitLab CI/CD pipelines by calling the API endpoint from the other provider's jobs. +For example, as part of a migration from [Jenkins](../migration/jenkins.md) or [CircleCI](../migration/circleci.md). + When authenticating with the API, you can use: - A [pipeline trigger token](#create-a-pipeline-trigger-token) to trigger a branch or tag pipeline. @@ -21,7 +24,7 @@ When authenticating with the API, you can use: You can trigger a pipeline for a branch or tag by generating a pipeline trigger token and using it to authenticate an API call. The token impersonates a user's project access and permissions. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index 0c05129fb1e..f247d9609fe 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD variables **(FREE ALL)** @@ -130,7 +129,7 @@ all variables become available to the pipeline. You can add CI/CD variables to a project's settings. -Prerequisite: +Prerequisites: - You must be a project member with the Maintainer role. @@ -159,7 +158,7 @@ or in [job scripts](#use-cicd-variables-in-job-scripts). You can make a CI/CD variable available to all projects in a group. -Prerequisite: +Prerequisites: - You must be a group member with the Owner role. @@ -188,14 +187,13 @@ are recursively inherited. You can make a CI/CD variable available to all projects and groups in a GitLab instance. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To add an instance variable: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD** and expand the **Variables** section. 1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. @@ -262,7 +260,7 @@ to prevent commands such as `env`/`printenv` from printing secret variables. You can mask a project, group, or instance CI/CD variable so the value of the variable does not display in job logs. -Prerequisite: +Prerequisites: - You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -306,7 +304,7 @@ temporary merge commit, not a branch or tag, do not have access to these variabl [Merge request pipelines](../pipelines/merge_request_pipelines.md), which do not use a temporary merge commit, can access these variables if the branch is a protected branch. -Prerequisite: +Prerequisites: - You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -626,7 +624,7 @@ Expanded variables treat values with the `$` character as a reference to another CI/CD variables are expanded by default. To treat variables with a `$` character as raw strings, disable variable expansion for the variable -Prerequisite: +Prerequisites: - You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -640,12 +638,15 @@ To disable variable expansion for the variable: ## CI/CD variable precedence +> Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. + You can use CI/CD variables with the same name in different places, but the values can overwrite each other. The type of variable and where they are defined determines which variables take precedence. The order of precedence for variables is (from highest to lowest): +1. [Scan Execution Policies variables](../../user/application_security/policies/scan-execution-policies.md). 1. These variables all have the same (highest) precedence: - [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call). - [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule). diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index cd23b903d30..e8ed47cedd0 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -1,150 +1,154 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Predefined variables reference **(FREE ALL)** +# Predefined CI/CD variables reference **(FREE ALL)** Predefined [CI/CD variables](index.md) are available in every GitLab CI/CD pipeline. -Some variables are only available with more recent versions of [GitLab Runner](https://docs.gitlab.com/runner/). +Predefined variables become available at two different phases of pipeline execution. +Some variables are available when GitLab creates the pipeline, and can be used to configure +the pipeline or in job scripts. The other variables become available when a runner runs the job, +and can only be used in job scripts. -You can [output the values of all variables available for a job](index.md#list-all-variables) -with a `script` command. +Predefined variables made available by the runner cannot be used with [trigger jobs](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file) +or these keywords: -There are also a number of [variables you can use to configure runner behavior](../runners/configure_runners.md#configure-runner-behavior-with-variables) globally or for individual jobs. +- [`workflow`](../yaml/index.md#workflow) +- [`include`](../yaml/index.md#include) +- [`rules`](../yaml/index.md#rules) NOTE: -You should avoid [overriding](index.md#override-a-defined-cicd-variable) predefined variables, +Avoid [overriding](index.md#override-a-defined-cicd-variable) predefined variables, as it can cause the pipeline to behave unexpectedly. -| Variable | GitLab | Runner | Description | -|------------------------------------------|--------|--------|-------------| -| `CHAT_CHANNEL` | 10.6 | all | The Source chat channel that triggered the [ChatOps](../chatops/index.md) command. | -| `CHAT_INPUT` | 10.6 | all | The additional arguments passed with the [ChatOps](../chatops/index.md) command. | -| `CHAT_USER_ID` | 14.4 | all | The chat service's user ID of the user who triggered the [ChatOps](../chatops/index.md) command. | -| `CI` | all | 0.4 | Available for all jobs executed in CI/CD. `true` when available. | -| `CI_API_V4_URL` | 11.7 | all | The GitLab API v4 root URL. | -| `CI_API_GRAPHQL_URL` | 15.11 | all | The GitLab API GraphQL root URL. | -| `CI_BUILDS_DIR` | all | 11.10 | The top-level directory where builds are executed. | -| `CI_COMMIT_AUTHOR` | 13.11 | all | The author of the commit in `Name <email>` format. | -| `CI_COMMIT_BEFORE_SHA` | 11.2 | all | The previous latest commit present on a branch or tag. Is always `0000000000000000000000000000000000000000` for merge request pipelines, the first commit in pipelines for branches or tags, or when manually running a pipeline. | -| `CI_COMMIT_BRANCH` | 12.6 | 0.5 | The commit branch name. Available in branch pipelines, including pipelines for the default branch. Not available in merge request pipelines or tag pipelines. | -| `CI_COMMIT_DESCRIPTION` | 10.8 | all | The description of the commit. If the title is shorter than 100 characters, the message without the first line. | -| `CI_COMMIT_MESSAGE` | 10.8 | all | The full commit message. | -| `CI_COMMIT_REF_NAME` | 9.0 | all | The branch or tag name for which project is built. | -| `CI_COMMIT_REF_PROTECTED` | 11.11 | all | `true` if the job is running for a protected reference, `false` otherwise. | -| `CI_COMMIT_REF_SLUG` | 9.0 | all | `CI_COMMIT_REF_NAME` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | -| `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](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) 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. | -| `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | The unique ID of build execution in a single executor and project. | -| `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | -| `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#enable-debug-logging) is enabled. | -| `CI_DEBUG_SERVICES` | 15.7 | 15.7 | `true` if [service container logging](../services/index.md#capturing-service-container-logs) is enabled. | -| `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | -| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | -| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | -| `CI_DEPENDENCY_PROXY_PASSWORD` | 13.7 | all | The password to pull images through the Dependency Proxy. | -| `CI_DEPENDENCY_PROXY_SERVER` | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | -| `CI_DEPENDENCY_PROXY_USER` | 13.7 | all | The username to pull images through the Dependency Proxy. | -| `CI_DEPLOY_FREEZE` | 13.2 | all | Only available if the pipeline runs during a [deploy freeze window](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). `true` when available. | -| `CI_DEPLOY_PASSWORD` | 10.8 | all | The authentication password of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | -| `CI_DEPLOY_USER` | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | -| `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. | -| `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/index.md#environmentname) is set. | -| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). A random suffix is automatically added to [uppercase environment names](https://gitlab.com/gitlab-org/gitlab/-/issues/415526). | -| `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 | Only available if [FIPS mode](../../development/fips_compliance.md) is enabled in the GitLab instance. `true` when available. | -| `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. | -| `CI_JOB_IMAGE` | 12.9 | 12.9 | The name of the Docker image running the job. | -| `CI_JOB_JWT` (Deprecated) | 12.10 | all | A RS256 JSON web token to authenticate with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | -| `CI_JOB_JWT_V1` (Deprecated) | 14.6 | all | The same value as `CI_JOB_JWT`. [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | -| `CI_JOB_JWT_V2` (Deprecated) | 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. 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). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | -| `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_TIMEOUT` | 15.7 | 15.7 | The job timeout, in seconds. | -| `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://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). | -| `CI_OPEN_MERGE_REQUESTS` | 13.8 | all | A comma-separated list of up to four merge requests that use the current branch and project as the merge request source. Only available in branch and merge request pipelines if the branch has an associated merge request. For example, `gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11`. | -| `CI_PAGES_DOMAIN` | 11.8 | all | The configured domain that hosts GitLab Pages. | -| `CI_PAGES_URL` | 11.8 | all | The URL for a GitLab Pages site. Always a subdomain of `CI_PAGES_DOMAIN`. | -| `CI_PIPELINE_ID` | 8.10 | all | The instance-level ID of the current pipeline. This ID is unique across all projects on the GitLab instance. | -| `CI_PIPELINE_IID` | 11.0 | all | The project-level IID (internal ID) of the current pipeline. This ID is unique only within the current project. | -| `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://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | -| `CI_PIPELINE_NAME` | 16.3 | all | The pipeline name defined in [`workflow:name`](../yaml/index.md#workflowname) | -| `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. | -| `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | -| `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) of the job. | -| `CI_PROJECT_NAMESPACE_ID` | 15.7 | 0.5 | The project namespace ID of the job. | -| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | -| `CI_PROJECT_PATH` | 8.10 | 0.5 | The project namespace with the project name included. | -| `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. The maximum number of languages is limited to 5. An issue [proposes to increase the limit](https://gitlab.com/gitlab-org/gitlab/-/issues/368925). | -| `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | -| `CI_PROJECT_TITLE` | 12.4 | all | The human-readable project name as displayed in the GitLab web interface. | -| `CI_PROJECT_DESCRIPTION` | 15.1 | all | The project description as displayed in the GitLab web interface. | -| `CI_PROJECT_URL` | 8.10 | 0.5 | The HTTP(S) address of the project. | -| `CI_PROJECT_VISIBILITY` | 10.3 | all | The project visibility. Can be `internal`, `private`, or `public`. | -| `CI_PROJECT_CLASSIFICATION_LABEL` | 14.2 | all | The project [external authorization classification label](../../administration/settings/external_authorization.md). | -| `CI_REGISTRY` | 8.10 | 0.5 | Address of the [Container Registry](../../user/packages/container_registry/index.md) server, formatted as `<host>[:<port>]`. For example: `registry.gitlab.example.com`. Only available if the Container Registry is enabled for the GitLab instance. | -| `CI_REGISTRY_IMAGE` | 8.10 | 0.5 | Base address for the container registry to push, pull, or tag project's images, formatted as `<host>[:<port>]/<project_full_path>`. For example: `registry.gitlab.example.com/my_group/my_project`. Image names must follow the [container registry naming convention](../../user/packages/container_registry/index.md#naming-convention-for-your-container-images). Only available if the Container Registry is enabled for the project. | -| `CI_REGISTRY_PASSWORD` | 9.0 | all | The password to push containers to the project's GitLab Container Registry. Only available if the Container Registry is enabled for the project. This password value is the same as the `CI_JOB_TOKEN` and is valid only as long as the job is running. Use the `CI_DEPLOY_PASSWORD` for long-lived access to the registry | -| `CI_REGISTRY_USER` | 9.0 | all | The username to push containers to the project's GitLab Container Registry. Only available if the Container Registry is enabled for the project. | -| `CI_REPOSITORY_URL` | 9.0 | all | The full path to Git clone (HTTP) the repository with a [CI/CD job token](../jobs/ci_job_token.md), in the format `https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/my-group/my-project.git`. | -| `CI_RUNNER_DESCRIPTION` | 8.10 | 0.5 | The description of the runner. | -| `CI_RUNNER_EXECUTABLE_ARCH` | all | 10.6 | The OS/architecture of the GitLab Runner executable. Might not be the same as the environment of the executor. | -| `CI_RUNNER_ID` | 8.10 | 0.5 | The unique ID of the runner being used. | -| `CI_RUNNER_REVISION` | all | 10.6 | The revision of the runner running the job. | -| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | The runner's unique ID, used to authenticate new job requests. In [GitLab 14.9](https://gitlab.com/gitlab-org/security/gitlab/-/merge_requests/2251) and later, the token contains a prefix, and the first 17 characters are used. Prior to 14.9, the first eight characters are used. | -| `CI_RUNNER_TAGS` | 8.10 | 0.5 | A comma-separated list of the runner tags. | -| `CI_RUNNER_VERSION` | all | 10.6 | The version of the GitLab Runner running the job. | -| `CI_SERVER_HOST` | 12.1 | all | The host of the GitLab instance URL, without protocol or port. For example `gitlab.example.com`. | -| `CI_SERVER_NAME` | all | all | The name of CI/CD server that coordinates jobs. | -| `CI_SERVER_PORT` | 12.8 | all | The port of the GitLab instance URL, without host or protocol. For example `8080`. | -| `CI_SERVER_PROTOCOL` | 12.8 | all | The protocol of the GitLab instance URL, without host or port. For example `https`. | -| `CI_SERVER_SHELL_SSH_HOST` | 15.11 | all | The SSH host of the GitLab instance, used for access to Git repositories via SSH. For example `gitlab.com`. | -| `CI_SERVER_SHELL_SSH_PORT` | 15.11 | all | The SSH port of the GitLab instance, used for access to Git repositories via SSH. For example `22`. | -| `CI_SERVER_REVISION` | all | all | GitLab revision that schedules jobs. | -| `CI_SERVER_TLS_CA_FILE` | all | all | File containing the TLS CA certificate to verify the GitLab server when `tls-ca-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_SERVER_TLS_CERT_FILE` | all | all | File containing the TLS certificate to verify the GitLab server when `tls-cert-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_SERVER_TLS_KEY_FILE` | all | all | File containing the TLS key to verify the GitLab server when `tls-key-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_SERVER_URL` | 12.7 | all | The base URL of the GitLab instance, including protocol and port. For example `https://gitlab.example.com:8080`. | -| `CI_SERVER_VERSION_MAJOR` | 11.4 | all | The major version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MAJOR` is `13`. | -| `CI_SERVER_VERSION_MINOR` | 11.4 | all | The minor version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MINOR` is `6`. | -| `CI_SERVER_VERSION_PATCH` | 11.4 | all | The patch version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_PATCH` is `1`. | -| `CI_SERVER_VERSION` | all | all | The full version of the GitLab instance. | -| `CI_SERVER` | all | all | Available for all jobs executed in CI/CD. `yes` when available. | -| `CI_SHARED_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a shared environment (something that is persisted across CI/CD invocations, like the `shell` or `ssh` executor). `true` when available. | -| `CI_TEMPLATE_REGISTRY_HOST` | 15.3 | all | The host of the registry used by CI/CD templates. Defaults to `registry.gitlab.com`. | -| `GITLAB_CI` | all | all | Available for all jobs executed in CI/CD. `true` when available. | -| `GITLAB_FEATURES` | 10.6 | all | The comma-separated list of licensed features available for the GitLab instance and license. | -| `GITLAB_USER_EMAIL` | 8.12 | all | The email of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the email of the user who started the job. | -| `GITLAB_USER_ID` | 8.12 | all | The numeric ID of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the ID of the user who started the job. | -| `GITLAB_USER_LOGIN` | 10.0 | all | The username of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the username of the user who started the job. | -| `GITLAB_USER_NAME` | 10.0 | all | The display name of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the name of the user who started the job. | -| `KUBECONFIG` | 14.2 | all | The path to the `kubeconfig` file with contexts for every shared agent connection. Only available when a [GitLab agent is authorized to access the project](../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent). | -| `TRIGGER_PAYLOAD` | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#access-webhook-payload). | +| Variable | Defined for | GitLab | Runner | Description | +|-----------------------------------|-------------|--------|--------|-------------| +| `CHAT_CHANNEL` | Pipeline | 10.6 | all | The Source chat channel that triggered the [ChatOps](../chatops/index.md) command. | +| `CHAT_INPUT` | Pipeline | 10.6 | all | The additional arguments passed with the [ChatOps](../chatops/index.md) command. | +| `CHAT_USER_ID` | Pipeline | 14.4 | all | The chat service's user ID of the user who triggered the [ChatOps](../chatops/index.md) command. | +| `CI` | Pipeline | all | 0.4 | Available for all jobs executed in CI/CD. `true` when available. | +| `CI_API_V4_URL` | Pipeline | 11.7 | all | The GitLab API v4 root URL. | +| `CI_API_GRAPHQL_URL` | Pipeline | 15.11 | all | The GitLab API GraphQL root URL. | +| `CI_BUILDS_DIR` | Jobs only | all | 11.10 | The top-level directory where builds are executed. | +| `CI_COMMIT_AUTHOR` | Pipeline | 13.11 | all | The author of the commit in `Name <email>` format. | +| `CI_COMMIT_BEFORE_SHA` | Pipeline | 11.2 | all | The previous latest commit present on a branch or tag. Is always `0000000000000000000000000000000000000000` for merge request pipelines, the first commit in pipelines for branches or tags, or when manually running a pipeline. | +| `CI_COMMIT_BRANCH` | Pipeline | 12.6 | 0.5 | The commit branch name. Available in branch pipelines, including pipelines for the default branch. Not available in merge request pipelines or tag pipelines. | +| `CI_COMMIT_DESCRIPTION` | Pipeline | 10.8 | all | The description of the commit. If the title is shorter than 100 characters, the message without the first line. | +| `CI_COMMIT_MESSAGE` | Pipeline | 10.8 | all | The full commit message. | +| `CI_COMMIT_REF_NAME` | Pipeline | 9.0 | all | The branch or tag name for which project is built. | +| `CI_COMMIT_REF_PROTECTED` | Pipeline | 11.11 | all | `true` if the job is running for a protected reference, `false` otherwise. | +| `CI_COMMIT_REF_SLUG` | Pipeline | 9.0 | all | `CI_COMMIT_REF_NAME` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | +| `CI_COMMIT_SHA` | Pipeline | 9.0 | all | The commit revision the project is built for. | +| `CI_COMMIT_SHORT_SHA` | Pipeline | 11.7 | all | The first eight characters of `CI_COMMIT_SHA`. | +| `CI_COMMIT_TAG` | Pipeline | 9.0 | 0.5 | The commit tag name. Available only in pipelines for tags. | +| `CI_COMMIT_TAG_MESSAGE` | Pipeline | 15.5 | all | The commit tag message. Available only in pipelines for tags. | +| `CI_COMMIT_TIMESTAMP` | Pipeline | 13.4 | all | The timestamp of the commit in the [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. For example, `2022-01-31T16:47:55Z`. | +| `CI_COMMIT_TITLE` | Pipeline | 10.8 | all | The title of the commit. The full first line of the message. | +| `CI_CONCURRENT_ID` | Jobs only | all | 11.10 | The unique ID of build execution in a single executor. | +| `CI_CONCURRENT_PROJECT_ID` | Jobs only | all | 11.10 | The unique ID of build execution in a single executor and project. | +| `CI_CONFIG_PATH` | Pipeline | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | +| `CI_DEBUG_TRACE` | Pipeline | all | 1.7 | `true` if [debug logging (tracing)](index.md#enable-debug-logging) is enabled. | +| `CI_DEBUG_SERVICES` | Pipeline | 15.7 | 15.7 | `true` if [service container logging](../services/index.md#capturing-service-container-logs) is enabled. | +| `CI_DEFAULT_BRANCH` | Pipeline | 12.4 | all | The name of the project's default branch. | +| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX`| Pipeline | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | Pipeline | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_PASSWORD` | Pipeline | 13.7 | all | The password to pull images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_SERVER` | Pipeline | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | +| `CI_DEPENDENCY_PROXY_USER` | Pipeline | 13.7 | all | The username to pull images through the Dependency Proxy. | +| `CI_DEPLOY_FREEZE` | Pipeline | 13.2 | all | Only available if the pipeline runs during a [deploy freeze window](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). `true` when available. | +| `CI_DEPLOY_PASSWORD` | Jobs only | 10.8 | all | The authentication password of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | +| `CI_DEPLOY_USER` | Jobs only | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | +| `CI_DISPOSABLE_ENVIRONMENT` | Pipeline | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. | +| `CI_ENVIRONMENT_NAME` | Pipeline | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/index.md#environmentname) is set. | +| `CI_ENVIRONMENT_SLUG` | Pipeline | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). A random suffix is automatically added to [uppercase environment names](https://gitlab.com/gitlab-org/gitlab/-/issues/415526). | +| `CI_ENVIRONMENT_URL` | Pipeline | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/index.md#environmenturl) is set. | +| `CI_ENVIRONMENT_ACTION` | Pipeline | 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` | Pipeline | 14.0 | all | The [deployment tier of the environment](../environments/index.md#deployment-tier-of-environments) for this job. | +| `CI_RELEASE_DESCRIPTION` | Pipeline | 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` | Pipeline | 14.10 | all | Only available if [FIPS mode](../../development/fips_compliance.md) is enabled in the GitLab instance. `true` when available. | +| `CI_HAS_OPEN_REQUIREMENTS` | Pipeline | 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` | Jobs only | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | +| `CI_JOB_IMAGE` | Pipeline | 12.9 | 12.9 | The name of the Docker image running the job. | +| `CI_JOB_JWT` (Deprecated) | Pipeline | 12.10 | all | A RS256 JSON web token to authenticate with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | +| `CI_JOB_JWT_V1` (Deprecated) | Pipeline | 14.6 | all | The same value as `CI_JOB_JWT`. [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | +| `CI_JOB_JWT_V2` (Deprecated) | Pipeline | 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. 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). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | +| `CI_JOB_MANUAL` | Pipeline | 8.12 | all | Only available if the job was started manually. `true` when available. | +| `CI_JOB_NAME` | Pipeline | 9.0 | 0.5 | The name of the job. | +| `CI_JOB_NAME_SLUG` | Pipeline | 15.4 | all | `CI_JOB_NAME` 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` | Pipeline | 9.0 | 0.5 | The name of the job's stage. | +| `CI_JOB_STATUS` | Jobs only | 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_TIMEOUT` | Jobs only | 15.7 | 15.7 | The job timeout, in seconds. | +| `CI_JOB_TOKEN` | Jobs only | 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` | Jobs only | 11.1 | 0.5 | The job details URL. | +| `CI_JOB_STARTED_AT` | Jobs only | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. For example, `2022-01-31T16:47:55Z`. | +| `CI_KUBERNETES_ACTIVE` | Pipeline | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. | +| `CI_NODE_INDEX` | Pipeline | 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` | Pipeline | 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). | +| `CI_OPEN_MERGE_REQUESTS` | Pipeline | 13.8 | all | A comma-separated list of up to four merge requests that use the current branch and project as the merge request source. Only available in branch and merge request pipelines if the branch has an associated merge request. For example, `gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11`. | +| `CI_PAGES_DOMAIN` | Pipeline | 11.8 | all | The configured domain that hosts GitLab Pages. | +| `CI_PAGES_URL` | Pipeline | 11.8 | all | The URL for a GitLab Pages site. Always a subdomain of `CI_PAGES_DOMAIN`. | +| `CI_PIPELINE_ID` | Jobs only | 8.10 | all | The instance-level ID of the current pipeline. This ID is unique across all projects on the GitLab instance. | +| `CI_PIPELINE_IID` | Pipeline | 11.0 | all | The project-level IID (internal ID) of the current pipeline. This ID is unique only within the current project. | +| `CI_PIPELINE_SOURCE` | Pipeline | 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` | Pipeline | all | all | `true` if the job was [triggered](../triggers/index.md). | +| `CI_PIPELINE_URL` | Jobs only | 11.1 | 0.5 | The URL for the pipeline details. | +| `CI_PIPELINE_CREATED_AT` | Pipeline | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. For example, `2022-01-31T16:47:55Z`. | +| `CI_PIPELINE_NAME` | Pipeline | 16.3 | all | The pipeline name defined in [`workflow:name`](../yaml/index.md#workflowname) | +| `CI_PROJECT_DIR` | Jobs only | 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` | Pipeline | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | +| `CI_PROJECT_NAME` | Pipeline | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | +| `CI_PROJECT_NAMESPACE` | Pipeline | 8.10 | 0.5 | The project namespace (username or group name) of the job. | +| `CI_PROJECT_NAMESPACE_ID` | Pipeline | 15.7 | 0.5 | The project namespace ID of the job. | +| `CI_PROJECT_PATH_SLUG` | Pipeline | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | +| `CI_PROJECT_PATH` | Pipeline | 8.10 | 0.5 | The project namespace with the project name included. | +| `CI_PROJECT_REPOSITORY_LANGUAGES` | Pipeline | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. The maximum number of languages is limited to 5. An issue [proposes to increase the limit](https://gitlab.com/gitlab-org/gitlab/-/issues/368925). | +| `CI_PROJECT_ROOT_NAMESPACE` | Pipeline | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | +| `CI_PROJECT_TITLE` | Pipeline | 12.4 | all | The human-readable project name as displayed in the GitLab web interface. | +| `CI_PROJECT_DESCRIPTION` | Pipeline | 15.1 | all | The project description as displayed in the GitLab web interface. | +| `CI_PROJECT_URL` | Pipeline | 8.10 | 0.5 | The HTTP(S) address of the project. | +| `CI_PROJECT_VISIBILITY` | Pipeline | 10.3 | all | The project visibility. Can be `internal`, `private`, or `public`. | +| `CI_PROJECT_CLASSIFICATION_LABEL` | Pipeline | 14.2 | all | The project [external authorization classification label](../../administration/settings/external_authorization.md). | +| `CI_REGISTRY` | Pipeline | 8.10 | 0.5 | Address of the [container registry](../../user/packages/container_registry/index.md) server, formatted as `<host>[:<port>]`. For example: `registry.gitlab.example.com`. Only available if the container registry is enabled for the GitLab instance. | +| `CI_REGISTRY_IMAGE` | Pipeline | 8.10 | 0.5 | Base address for the container registry to push, pull, or tag project's images, formatted as `<host>[:<port>]/<project_full_path>`. For example: `registry.gitlab.example.com/my_group/my_project`. Image names must follow the [container registry naming convention](../../user/packages/container_registry/index.md#naming-convention-for-your-container-images). Only available if the container registry is enabled for the project. | +| `CI_REGISTRY_PASSWORD` | Jobs only | 9.0 | all | The password to push containers to the GitLab project's container registry. Only available if the container registry is enabled for the project. This password value is the same as the `CI_JOB_TOKEN` and is valid only as long as the job is running. Use the `CI_DEPLOY_PASSWORD` for long-lived access to the registry | +| `CI_REGISTRY_USER` | Jobs only | 9.0 | all | The username to push containers to the project's GitLab container registry. Only available if the container registry is enabled for the project. | +| `CI_REPOSITORY_URL` | Jobs only | 9.0 | all | The full path to Git clone (HTTP) the repository with a [CI/CD job token](../jobs/ci_job_token.md), in the format `https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/my-group/my-project.git`. | +| `CI_RUNNER_DESCRIPTION` | Jobs only | 8.10 | 0.5 | The description of the runner. | +| `CI_RUNNER_EXECUTABLE_ARCH` | Jobs only | all | 10.6 | The OS/architecture of the GitLab Runner executable. Might not be the same as the environment of the executor. | +| `CI_RUNNER_ID` | Jobs only | 8.10 | 0.5 | The unique ID of the runner being used. | +| `CI_RUNNER_REVISION` | Jobs only | all | 10.6 | The revision of the runner running the job. | +| `CI_RUNNER_SHORT_TOKEN` | Jobs only | all | 12.3 | The runner's unique ID, used to authenticate new job requests. In [GitLab 14.9](https://gitlab.com/gitlab-org/security/gitlab/-/merge_requests/2251) and later, the token contains a prefix, and the first 17 characters are used. Prior to 14.9, the first eight characters are used. | +| `CI_RUNNER_TAGS` | Jobs only | 8.10 | 0.5 | A comma-separated list of the runner tags. | +| `CI_RUNNER_VERSION` | Jobs only | all | 10.6 | The version of the GitLab Runner running the job. | +| `CI_SERVER_HOST` | Pipeline | 12.1 | all | The host of the GitLab instance URL, without protocol or port. For example `gitlab.example.com`. | +| `CI_SERVER_NAME` | Pipeline | all | all | The name of CI/CD server that coordinates jobs. | +| `CI_SERVER_PORT` | Pipeline | 12.8 | all | The port of the GitLab instance URL, without host or protocol. For example `8080`. | +| `CI_SERVER_PROTOCOL` | Pipeline | 12.8 | all | The protocol of the GitLab instance URL, without host or port. For example `https`. | +| `CI_SERVER_SHELL_SSH_HOST` | Pipeline | 15.11 | all | The SSH host of the GitLab instance, used for access to Git repositories via SSH. For example `gitlab.com`. | +| `CI_SERVER_SHELL_SSH_PORT` | Pipeline | 15.11 | all | The SSH port of the GitLab instance, used for access to Git repositories via SSH. For example `22`. | +| `CI_SERVER_REVISION` | Pipeline | all | all | GitLab revision that schedules jobs. | +| `CI_SERVER_TLS_CA_FILE` | Pipeline | all | all | File containing the TLS CA certificate to verify the GitLab server when `tls-ca-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_SERVER_TLS_CERT_FILE` | Pipeline | all | all | File containing the TLS certificate to verify the GitLab server when `tls-cert-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_SERVER_TLS_KEY_FILE` | Pipeline | all | all | File containing the TLS key to verify the GitLab server when `tls-key-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_SERVER_URL` | Pipeline | 12.7 | all | The base URL of the GitLab instance, including protocol and port. For example `https://gitlab.example.com:8080`. | +| `CI_SERVER_VERSION_MAJOR` | Pipeline | 11.4 | all | The major version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MAJOR` is `13`. | +| `CI_SERVER_VERSION_MINOR` | Pipeline | 11.4 | all | The minor version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MINOR` is `6`. | +| `CI_SERVER_VERSION_PATCH` | Pipeline | 11.4 | all | The patch version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_PATCH` is `1`. | +| `CI_SERVER_VERSION` | Pipeline | all | all | The full version of the GitLab instance. | +| `CI_SERVER` | Jobs only | all | all | Available for all jobs executed in CI/CD. `yes` when available. | +| `CI_SHARED_ENVIRONMENT` | Pipeline | all | 10.1 | Only available if the job is executed in a shared environment (something that is persisted across CI/CD invocations, like the `shell` or `ssh` executor). `true` when available. | +| `CI_TEMPLATE_REGISTRY_HOST` | Pipeline | 15.3 | all | The host of the registry used by CI/CD templates. Defaults to `registry.gitlab.com`. | +| `GITLAB_CI` | Pipeline | all | all | Available for all jobs executed in CI/CD. `true` when available. | +| `GITLAB_FEATURES` | Pipeline | 10.6 | all | The comma-separated list of licensed features available for the GitLab instance and license. | +| `GITLAB_USER_EMAIL` | Pipeline | 8.12 | all | The email of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the email of the user who started the job. | +| `GITLAB_USER_ID` | Pipeline | 8.12 | all | The numeric ID of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the ID of the user who started the job. | +| `GITLAB_USER_LOGIN` | Pipeline | 10.0 | all | The username of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the username of the user who started the job. | +| `GITLAB_USER_NAME` | Pipeline | 10.0 | all | The display name of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the name of the user who started the job. | +| `KUBECONFIG` | Pipeline | 14.2 | all | The path to the `kubeconfig` file with contexts for every shared agent connection. Only available when a [GitLab agent is authorized to access the project](../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent). | +| `TRIGGER_PAYLOAD` | Pipeline | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#access-webhook-payload). | ## Predefined variables for merge request pipelines @@ -157,7 +161,11 @@ These variables are available when: |---------------------------------------------|--------|--------|-------------| | `CI_MERGE_REQUEST_APPROVED` | 14.1 | all | Approval status of the merge request. `true` when [merge request approvals](../../user/project/merge_requests/approvals/index.md) is available and the merge request has been approved. | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of usernames of assignees for the merge request. | +| `CI_MERGE_REQUEST_DIFF_BASE_SHA` | 13.7 | all | The base SHA of the merge request diff. | +| `CI_MERGE_REQUEST_DIFF_ID` | 13.7 | all | The version of the merge request diff. | +| `CI_MERGE_REQUEST_EVENT_TYPE` | 12.3 | all | The event type of the merge request. Can be `detached`, `merged_result` or `merge_train`. | | `CI_MERGE_REQUEST_ID` | 11.6 | all | The instance-level ID of the merge request. This is a unique ID across all projects on the GitLab instance. | +| `CI_MERGE_REQUEST_DESCRIPTION` | 16.7 | all | The description of the merge request. | | `CI_MERGE_REQUEST_IID` | 11.6 | all | The project-level IID (internal ID) of the merge request. This ID is unique for the current project, and is the number used in the merge request URL, page title, and other visible locations. | | `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request. | | `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request. | @@ -165,20 +173,17 @@ These variables are available when: | `CI_MERGE_REQUEST_PROJECT_PATH` | 11.6 | all | The path of the project of the merge request. For example `namespace/awesome-project`. | | `CI_MERGE_REQUEST_PROJECT_URL` | 11.6 | all | The URL of the project of the merge request. For example, `http://192.168.10.15:3000/namespace/awesome-project`. | | `CI_MERGE_REQUEST_REF_PATH` | 11.6 | all | The ref path of the merge request. For example, `refs/merge-requests/1/head`. | -| `CI_MERGE_REQUEST_SQUASH_ON_MERGE` | 16.4 | all | `true` when the [squash on merge](../../user/project/merge_requests/squash_and_merge.md) option is set. | | `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | 11.6 | all | The source branch name of the merge request. | | `CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED` | 16.4 | all | `true` when the source branch of the merge request is [protected](../../user/project/protected_branches.md). | | `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the source branch of the merge request. The variable is empty in merge request pipelines. The SHA is present only in [merged results pipelines](../pipelines/merged_results_pipelines.md). | | `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | 11.6 | all | The ID of the source project of the merge request. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | 11.6 | all | The path of the source project of the merge request. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | 11.6 | all | The URL of the source project of the merge request. | +| `CI_MERGE_REQUEST_SQUASH_ON_MERGE` | 16.4 | all | `true` when the [squash on merge](../../user/project/merge_requests/squash_and_merge.md) option is set. | | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request. | | `CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED` | 15.2 | all | `true` when the target branch of the merge request is [protected](../../user/project/protected_branches.md). | | `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch of the merge request. The variable is empty in merge request pipelines. The SHA is present only in [merged results pipelines](../pipelines/merged_results_pipelines.md). | | `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request. | -| `CI_MERGE_REQUEST_EVENT_TYPE` | 12.3 | all | The event type of the merge request. Can be `detached`, `merged_result` or `merge_train`. | -| `CI_MERGE_REQUEST_DIFF_ID` | 13.7 | all | The version of the merge request diff. | -| `CI_MERGE_REQUEST_DIFF_BASE_SHA` | 13.7 | all | The base SHA of the merge request diff. | ## Predefined variables for external pull request pipelines @@ -208,3 +213,8 @@ defines deployment variables that you can use with the integration. The [documentation for each integration](../../user/project/integrations/index.md) explains if the integration has any deployment variables available. + +## Troubleshooting + +You can [output the values of all variables available for a job](index.md#list-all-variables) +with a `script` command. diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index d25f9801f5b..bddb0947fac 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Where variables can be used **(FREE ALL)** @@ -149,15 +148,15 @@ Pipeline-level persisted variables: Job-level persisted variables: +- `CI_DEPLOY_PASSWORD` +- `CI_DEPLOY_USER` - `CI_JOB_ID` -- `CI_JOB_URL` -- `CI_JOB_TOKEN` - `CI_JOB_STARTED_AT` -- `CI_REGISTRY_USER` +- `CI_JOB_TOKEN` +- `CI_JOB_URL` - `CI_REGISTRY_PASSWORD` +- `CI_REGISTRY_USER` - `CI_REPOSITORY_URL` -- `CI_DEPLOY_USER` -- `CI_DEPLOY_PASSWORD` Persisted variables are: diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index e931a8b3b4e..5867a5b3506 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD artifacts reports types **(FREE ALL)** @@ -17,7 +17,8 @@ Use [`artifacts:reports`](index.md#artifactsreports) to: Artifacts created for `artifacts: reports` are always uploaded, regardless of the job results (success or failure). You can use [`artifacts:expire_in`](index.md#artifactsexpire_in) to set an expiration -date for the artifacts. +time for the artifacts, which overrides the instance's [default setting](../../administration/settings/continuous_integration.md#maximum-artifacts-size). +GitLab.com might have a [different default artifacts expiry value](../../user/gitlab_com/index.md#gitlab-cicd). Some `artifacts:reports` types can be generated by multiple jobs in the same pipeline, and used by merge request or pipeline features from each job. @@ -30,8 +31,6 @@ not supported. Track progress on adding support in [this issue](https://gitlab.c ## `artifacts:reports:accessibility` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 12.8. - The `accessibility` report uses [pa11y](https://pa11y.org/) to report on the accessibility impact of changes introduced in merge requests. @@ -91,9 +90,6 @@ The following is an example of what a job annotations report might look like: ## `artifacts:reports:api_fuzzing` **(ULTIMATE ALL)** -> - Introduced in GitLab 13.4. -> - Requires GitLab Runner 13.4 or later. - The `api_fuzzing` report collects [API Fuzzing bugs](../../user/application_security/api_fuzzing/index.md) as artifacts. @@ -143,8 +139,7 @@ GitLab can display the results of coverage report in the merge request ## `artifacts:reports:codequality` -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. -> - Support for multiple reports in diff annotations and full pipeline report [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9014) in 15.7. +> Support for multiple reports in diff annotations and full pipeline report [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9014) in 15.7. The `codequality` report collects [code quality issues](../testing/code_quality.md). The collected code quality report uploads to GitLab as an artifact. @@ -155,6 +150,8 @@ GitLab can display the results of one or more reports in: - The merge request [diff annotations](../testing/code_quality.md#merge-request-changes-view). - The [full report](../testing/metrics_reports.md). +The [`artifacts:expire_in`](../yaml/index.md#artifactsexpire_in) value is set to `1 week`. + ## `artifacts:reports:container_scanning` **(ULTIMATE ALL)** The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md). @@ -169,9 +166,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:coverage_fuzzing` **(ULTIMATE ALL)** -> - Introduced in GitLab 13.4. -> - Requires GitLab Runner 13.4 or later. - The `coverage_fuzzing` report collects [coverage fuzzing bugs](../../user/application_security/coverage_fuzzing/index.md). The collected coverage fuzzing report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: @@ -233,8 +227,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:dotenv` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9. - The `dotenv` report collects a set of environment variables as artifacts. The collected variables are registered as runtime-created variables of the job, @@ -294,24 +286,8 @@ concatenate them into a single file. Use either: - A combination of both (`junit: [rspec.xml, test-results/TEST-*.xml]`). - Directories are not supported(`junit: test-results`, `junit: test-results/**`). -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> - -## `artifacts:reports:license_scanning` **(ULTIMATE ALL)** - -> Introduced in GitLab 12.8. - -The license scanning report was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) -in GitLab 15.9 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) in GitLab 16.3. -You should instead migrate to use [License approval policies](../../user/compliance/license_approval_policies.md) and -the [new method of license scanning](../../user/compliance/license_scanning_of_cyclonedx_files/index.md). - -<!--- end_remove --> - ## `artifacts:reports:load_performance` **(PREMIUM ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. -> - Requires GitLab Runner 11.5 and above. - The `load_performance` report collects [Load Performance Testing metrics](../testing/load_performance_testing.md). The report is uploaded to GitLab as an artifact. @@ -330,14 +306,18 @@ GitLab can display the results of one or more reports in the merge request ## `artifacts:reports:requirements` **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. - The `requirements` report collects `requirements.json` files. The collected Requirements report uploads to GitLab as an artifact and existing [requirements](../../user/project/requirements/index.md) are marked as Satisfied. GitLab can display the results of one or more reports in the [project requirements](../../user/project/requirements/index.md#view-a-requirement). +## `artifacts:reports:repository_xray` **(ULTIMATE ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432235) in GitLab 16.7. + +The `repository_xray` report collects information about your repository for use by AI in code suggestions. + ## `artifacts:reports:sast` > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. @@ -352,10 +332,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:secret_detection` -> - Introduced in GitLab 13.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) to GitLab Free in 13.3. -> - Requires GitLab Runner 11.5 and above. - The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md). The collected Secret Detection report is uploaded to GitLab. @@ -367,9 +343,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:terraform` -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. -> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. - The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/iac/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform plan report uploads to GitLab as an artifact. diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index f0e5a475838..8da4195f5aa 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use CI/CD configuration from other files **(FREE ALL)** diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 9b781ca6d13..df2330e04f6 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD YAML syntax reference **(FREE ALL)** @@ -55,13 +54,11 @@ A GitLab CI/CD pipeline configuration includes: | [`dast_configuration`](#dast_configuration) | Use configuration from DAST profiles on a job level. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | | [`environment`](#environment) | Name of an environment to which the job deploys. | - | [`except`](#only--except) | Control when jobs are not created. | | [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. | | [`inherit`](#inherit) | Select which global defaults all jobs inherit. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | | [`needs`](#needs) | Execute jobs earlier than the stage ordering. | - | [`only`](#only--except) | Control when jobs are created. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`release`](#release) | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. | @@ -193,6 +190,27 @@ The time limit to resolve all files is 30 seconds. - [Use variables with `include`](includes.md#use-variables-with-include). - [Use `rules` with `include`](includes.md#use-rules-with-include). +#### `include:component` + +Use `include:component` to add a [CI/CD component](../components/index.md) to the +pipeline configuration. + +**Keyword type**: Global keyword. + +**Possible inputs**: The full address of the CI/CD component, formatted as +`<fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>`. + +**Example of `include:component`**: + +```yaml +include: + - component: gitlab.example.com/my-org/security-components/secret-detection@1.0 +``` + +**Related topics**: + +- [Use a CI/CD component](../components/index.md#use-a-component). + #### `include:local` Use `include:local` to include a file that is in the same repository and branch as the configuration file containing the `include` keyword. @@ -454,6 +472,9 @@ start. Jobs in the current stage are not stopped and continue to run. Use [`workflow`](workflow.md) to control pipeline behavior. +You can use some [predefined CI/CD variables](../variables/predefined_variables.md) in +`workflow` configuration, but not variables that are only defined when jobs start. + **Related topics**: - [`workflow: rules` examples](workflow.md#workflow-rules-examples) @@ -499,6 +520,7 @@ workflow: - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/' variables: PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline' + - when: always # Other pipelines can run, but use the default name ``` **Additional details**: @@ -727,8 +749,11 @@ In this example: **Additional details**: -- If an input uses both `default` and [`options`](#specinputsoptions), the default value - must be one of the listed options. If not, the pipeline fails with a validation error. +- The pipeline fails with a validation error when the input: + - Uses both `default` and [`options`](#specinputsoptions), but the default value + is not one of the listed options. + - Uses both `default` and `regex`, but the default value does not match the regular expression. + - Value does not match the [`type`](#specinputstype). ##### `spec:inputs:description` @@ -788,8 +813,42 @@ In this example: **Additional details**: -- If an input uses both [`default`](#specinputsdefault) and `options`, the default value - must be one of the listed options. If not, the pipeline fails with a validation error. +- The pipeline fails with a validation error when: + - The input uses both `options` and [`default`](#specinputsdefault), but the default value + is not one of the listed options. + - Any of the input options do not match the [`type`](#specinputstype), which can + be either `string` or `number`, but not `boolean` when using `options`. + +##### `spec:inputs:regex` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410836) in GitLab 16.5. + +Use `spec:inputs:regex` to specify a regular expression that the input must match. + +**Keyword type**: Header keyword. `specs` must be declared at the top of the configuration file, +in a header section. + +**Possible inputs**: Must be a regular expression that starts and ends with the `/` character. + +**Example of `spec:inputs:regex`**: + +```yaml +spec: + inputs: + version: + regex: /^v\d\.\d+(\.\d+)$/ +--- + +# The pipeline configuration would follow... +``` + +In this example, inputs of `v1.0` or `v1.2.3` match the regular expression and pass validation. +An input of `v1.A.B` does not match the regular expression and fails validation. + +**Additional details**: + +- `inputs:regex` can only be used with a [`type`](#specinputstype) of `string`, + not `number` or `boolean`. ##### `spec:inputs:type` @@ -1213,6 +1272,7 @@ job: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223273) in GitLab 13.8 [with a flag](../../user/feature_flags.md) named `non_public_artifacts`, disabled by default. > - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/322454) in GitLab 15.10. Artifacts created with `artifacts:public` before 15.10 are not guaranteed to remain private after this update. +> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/294503) in GitLab 16.7. Rolled out and removed a feature flag named `non_public_artifacts` WARNING: On self-managed GitLab, by default this feature is not available. To make it available, @@ -2041,7 +2101,7 @@ stop_review_app: #### `environment:auto_stop_in` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8. +> CI/CD variable support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365140) in GitLab 15.4. The `auto_stop_in` keyword specifies the lifetime of the environment. When an environment expires, GitLab automatically stops it. @@ -2056,6 +2116,8 @@ these are all equivalent: - `one week` - `never` +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `environment:auto_stop_in`**: ```yaml @@ -2404,6 +2466,37 @@ image: - [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image). +#### `image:docker` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later. + +Use `image:docker` to pass options to the Docker executor of a GitLab Runner. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: + +A hash of options for the Docker executor, which can include: + +- `platform`: Selects the architecture of the image to pull. When not specified, + the default is the same platform as the host runner. + +**Example of `image:docker`**: + +```yaml +arm-sql-job: + script: echo "Run sql tests" + image: + name: super/sql:experimental + docker: + platform: arm64/v8 +``` + +**Additional details**: + +- `image:docker:platform` maps to the [`docker pull --platform` option](https://docs.docker.com/engine/reference/commandline/pull/#options). + #### `image:pull_policy` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default. @@ -2444,8 +2537,8 @@ job2: **Related topics**: - [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -- [How runner pull policies work](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work). -- [Using multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#using-multiple-pull-policies). +- [Configure how runners pull images](https://docs.gitlab.com/runner/executors/docker.html#configure-how-runners-pull-images). +- [Set multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#set-multiple-pull-policies). ### `inherit` @@ -2529,13 +2622,22 @@ job2: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. +Use `interruptible` to configure the [auto-cancel redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +feature to cancel a job before it completes if a new pipeline on the same ref starts for a newer commit. If the feature +is disabled, the keyword has no effect. -This keyword has no effect if [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) -is disabled. When enabled, a running job with `interruptible: true` is cancelled when -starting a pipeline for a new change on the same branch. +**Running** jobs are only cancelled when the jobs are configured with `interruptible: true` and: -You can't cancel subsequent jobs after a job with `interruptible: false` starts. +- No jobs configured with `interruptible: false` have started at any time. + After a job with `interruptible: false` starts, the entire pipeline is no longer + considered interruptible. + - If the pipeline triggered a downstream pipeline, but no job with `interruptible: false` + in the downstream pipeline has started yet, the downstream pipeline is also cancelled. +- The new pipeline is for a commit with new changes. The **Auto-cancel redundant pipelines** + feature has no effect if you select **Run pipeline** in the UI to run a pipeline for the same commit. + +A job that has not started yet is always considered `interruptible: true`, regardless of the job's configuration. +The `interruptible` configuration is only considered after the job starts. **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -2579,11 +2681,10 @@ In this example, a new pipeline causes a running pipeline to be: - Only set `interruptible: true` if the job can be safely canceled after it has started, like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. -- To completely cancel a running pipeline, all jobs must have `interruptible: true`, - or `interruptible: false` jobs must not have started. -- Running jobs are only cancelled if the newer pipeline has new changes. - For example, a running job is not be cancelled if you run a new pipeline for the same - commit by selecting **Run pipeline** in the UI. +- You can add an optional manual job with `interruptible: false` in the first stage of + a pipeline to allow users to manually prevent a pipeline from being automatically + cancelled. After a user starts the job, the pipeline cannot be canceled by the + **Auto-cancel redundant pipelines** feature. ### `needs` @@ -3051,7 +3152,7 @@ pages: environment: production ``` -This example moves all files from a `my-html-content/` directory to the `public/` directory. +This example renames the `my-html-content/` directory to `public/`. This directory is exported as an artifact and published with GitLab Pages. #### `pages:publish` @@ -3084,6 +3185,41 @@ This example uses [Eleventy](https://www.11ty.dev) to generate a static website output the generated HTML files into a the `dist/` directory. This directory is exported as an artifact and published with GitLab Pages. +#### `pages:pages.path_prefix` **(PREMIUM ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [Experiment](../../policy/experiment-beta-support.md) [with a flag](../../user/feature_flags.md) named `pages_multiple_versions_setting`, disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../administration/feature_flags.md) named +`pages_multiple_versions_setting`. On GitLab.com, this feature is not available. This feature is not ready for production use. + +Use `pages.path_prefix` to configure a path prefix for [multiple deployments](../../user/project/pages/index.md#create-multiple-deployments) of GitLab Pages. + +**Keyword type**: Job keyword. You can use it only as part of a `pages` job. + +**Possible inputs**: + +- A string with valid [URL characters](https://www.ietf.org/rfc/rfc1738.txt). +- [CI/CD variables](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). +- A combination of both. + +**Example of `pages.path_prefix`**: + +```yaml +pages: + stage: deploy + script: + - echo "Pages accessible through ${CI_PAGES_URL}/${CI_COMMIT_BRANCH}" + pages: + path_prefix: "$CI_COMMIT_BRANCH" + artifacts: + paths: + - public +``` + +In this example, a different pages deployment is created for each branch. + ### `parallel` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum value for `parallel` is increased from 50 to 200. @@ -3222,7 +3358,7 @@ The release job must have access to the [`release-cli`](https://gitlab.com/gitla which must be in the `$PATH`. If you use the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html), -you can use this image from the GitLab Container Registry: `registry.gitlab.com/gitlab-org/release-cli:latest` +you can use this image from the GitLab container registry: `registry.gitlab.com/gitlab-org/release-cli:latest` If you use the [Shell executor](https://docs.gitlab.com/runner/executors/shell.html) or similar, [install `release-cli`](../../user/project/releases/release_cli.md) on the server where the runner is registered. @@ -3556,7 +3692,7 @@ Use `retry:when` with `retry:max` to retry jobs for only specific failure cases. - `archived_failure`: Retry if the job is archived and can't be run. - `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks. - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner. -- `data_integrity_failure`: Retry if there is a structural integrity problem detected. +- `data_integrity_failure`: Retry if there is an unknown job problem. **Example of `retry:when`** (single failure type): @@ -3706,8 +3842,6 @@ An array including any number of: - 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"`. @@ -3735,6 +3869,9 @@ docker build: **Additional details**: - `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges). +- Glob patterns are interpreted with Ruby's [`File.fnmatch`](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + with the [flags](https://docs.ruby-lang.org/en/master/File/Constants.html#module-File::Constants-label-Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29) + `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. - You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges). - `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). @@ -3838,8 +3975,9 @@ job: **Additional details**: -- Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch) - with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. +- Glob patterns are interpreted with Ruby's [`File.fnmatch`](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + with the [flags](https://docs.ruby-lang.org/en/master/File/Constants.html#module-File::Constants-label-Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29) + `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. - For performance reasons, GitLab performs a maximum of 10,000 checks against `exists` patterns or file paths. After the 10,000th check, rules with patterned globs always match. In other words, the `exists` rule always assumes a match in @@ -3995,7 +4133,7 @@ job2: **Additional details**: -- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`) . +- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`). **Related topics**: @@ -4210,7 +4348,39 @@ In this example, GitLab launches two containers for the job: - [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). - [Use Docker to build Docker images](../docker/using_docker_build.md). -#### `service:pull_policy` +#### `services:docker` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later. + +Use `services:docker` to pass options to the Docker executor of a GitLab Runner. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: + +A hash of options for the Docker executor, which can include: + +- `platform`: Selects the architecture of the image to pull. When not specified, + the default is the same platform as the host runner. + +**Example of `services:docker`**: + +```yaml +arm-sql-job: + script: echo "Run sql tests in service container" + image: ruby:2.6 + services: + - name: super/sql:experimental + docker: + platform: arm64/v8 +``` + +**Additional details**: + +- `services:docker:platform` maps to the [`docker pull --platform` option](https://docs.docker.com/engine/reference/commandline/pull/#options). + +#### `services:pull_policy` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.2. @@ -4226,7 +4396,7 @@ The pull policy that the runner uses to fetch the Docker image. - A single pull policy, or multiple pull policies in an array. Can be `always`, `if-not-present`, or `never`. -**Examples of `service:pull_policy`**: +**Examples of `services:pull_policy`**: ```yaml job1: @@ -4250,8 +4420,8 @@ job2: **Related topics**: - [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -- [How runner pull policies work](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work). -- [Using multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#using-multiple-pull-policies). +- [Configure how runners pull images](https://docs.gitlab.com/runner/executors/docker.html#configure-how-runners-pull-images). +- [Set multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#set-multiple-pull-policies). ### `stage` @@ -4420,7 +4590,7 @@ In this example, only runners with *both* the `ruby` and `postgres` tags can run **Related topics**: -- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). +- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#control-jobs-that-a-runner-can-run). - [Select different runner tags for each parallel matrix job](../jobs/job_control.md#select-different-runner-tags-for-each-parallel-matrix-job). ### `timeout` @@ -4431,7 +4601,7 @@ Use `timeout` to configure a timeout for a specific job. If the job runs for lon than the timeout, the job fails. The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run), -but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-the-maximum-job-timeout). **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -4670,6 +4840,13 @@ child3: yaml_variables: false ``` +**Additional details**: + +- CI/CD variables forwarded to downstream pipelines with `trigger:forward` have the + [highest precedence](../variables/index.md#cicd-variable-precedence). If a variable + with the same name is defined in the downstream pipeline, that variable is overwritten + by the forwarded variable. + ### `variables` Use `variables` to define [CI/CD variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) for jobs. @@ -5121,12 +5298,11 @@ Use `changes` in pipelines with the following refs: **Possible inputs**: An array including any number of: - Paths to files. -- Wildcard paths for single directories, for example `path/to/directory/*`, or 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 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}`. - Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. For example `"*.json"` or `"**/*.json"`. @@ -5149,6 +5325,9 @@ docker build: **Additional details**: - `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). +- Glob patterns are interpreted with Ruby's [`File.fnmatch`](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + with the [flags](https://docs.ruby-lang.org/en/master/File/Constants.html#module-File::Constants-label-Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29) + `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. - If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, `changes` can't determine if a given file is new or old and always returns `true`. - If you use `only: changes` with other refs, jobs ignore the changes and always run. diff --git a/doc/ci/yaml/inputs.md b/doc/ci/yaml/inputs.md index 089d6bc5b62..0869be6da9f 100644 --- a/doc/ci/yaml/inputs.md +++ b/doc/ci/yaml/inputs.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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Define inputs for configuration added with `include` **(FREE ALL)** @@ -9,19 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a Beta feature. > - Made generally available in GitLab 16.6. -## Define input parameters with `spec:inputs` +Use inputs to increase the flexibility of CI/CD configuration files that are designed +to be reused. + +Inputs can use CI/CD variables, but have the same [variable limitations as the `include` keyword](includes.md#use-variables-with-include). -> - `description` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415637) in GitLab 16.5. -> - `options` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393401) in GitLab 16.6. +## Define input parameters with `spec:inputs` Use `spec:inputs` to define input parameters for CI/CD configuration intended to be added to a pipeline with `include`. Use [`include:inputs`](#set-input-values-when-using-include) -to define the values to use when the pipeline runs. +to pass input values when building the configuration for a pipeline. The specs must be declared at the top of the configuration file, in a header section. Separate the header from the rest of the configuration with `---`. -Use the interpolation format `$[[ input.input-id ]]` to reference the values outside of the header section. +Use the interpolation format `$[[ inputs.input-id ]]` outside the header section to replace the values. The inputs are evaluated and interpolated when the configuration is fetched during pipeline creation, but before the configuration is merged with the contents of the `.gitlab-ci.yml` file. @@ -42,9 +44,9 @@ scan-website: When using `spec:inputs`: - Inputs are mandatory by default. -- Inputs must be strings by default. -- A string containing an interpolation block must not exceed 1 MB. -- The string inside an interpolation block must not exceed 1 KB. +- Validation errors are returned if: + - A string containing an interpolation block exceeds 1 MB. + - The string inside an interpolation block exceeds 1 KB. Additionally, use: @@ -55,8 +57,53 @@ Additionally, use: understand the input details or expected values. - [`spec:inputs:options`](index.md#specinputsoptions) to specify a list of allowed values for an input. +- [`spec:inputs:regex`](index.md#specinputsoptions) to specify a regular expression + that the input must match. - [`spec:inputs:type`](index.md#specinputstype) to force a specific input type, which - can be `string` (the default type), `number`, or `boolean`. + can be `string` (default when not specified), `number`, or `boolean`. + +### Define inputs with multiple parameters + +You can define multiple inputs per CI/CD configuration file, and each input can have +multiple configuration parameters. + +For example, in a file named `scan-website-job.yml`: + +```yaml +spec: + inputs: + job-prefix: # Mandatory string input + description: "Define a prefix for the job name" + job-stage: # Optional string input with a default value when not provided + default: test + environment: # Mandatory input that must match one of the options + options: ['test', 'staging', 'production'] + concurrency: + type: number # Optional numeric input with a default value when not provided + default: 1 + version: # Mandatory string input that must match the regular expression + type: string + regex: /^v\d\.\d+(\.\d+)$/ + export_results: # Optional boolean input with a default value when not provided + type: boolean + default: true +--- + +"$[[ job-prefix ]]-scan-website": + stage: $[[ inputs.job-stage ]] + script: + - echo "scanning website -e $[[ inputs.environment ]] -c $[[ inputs.concurrency ]] -v $[[ inputs.version ]]" + - if [ $[[ inputs.export_results ]] ]; then echo "export results"; fi +``` + +In this example: + +- `job-prefix` is a mandatory string input and must be defined. +- `job-stage` is optional. If not defined, the value is `test`. +- `environment` is a mandatory string input that must match one of the defined options. +- `concurrency` is an optional numeric input. When not specified, it defaults to `1`. +- `version` is a mandatory string input that must match the specified regular expression. +- `export_results` is an optional boolean input. When not specified, it defaults to `true`. ## Set input values when using `include` @@ -65,29 +112,29 @@ Additionally, use: Use [`include:inputs`](index.md#includeinputs) to set the values for the parameters when the included configuration is added to the pipeline. -For example, to include a `custom_website_scan.yml` that has the same specs -as the [example above](#define-input-parameters-with-specinputs): +For example, to include the `scan-website-job.yml` in the [example above](#define-inputs-with-multiple-parameters): ```yaml include: - - local: 'custom_website_scan.yml' + - local: 'scan-website-job.yml' inputs: - job-stage: post-deploy - environment: production - -stages: - - build - - test - - deploy - - post-deploy - -# The pipeline configuration would follow... + job-prefix: 'some-service-' + environment: 'staging' + concurrency: 2 + version: 'v1.3.2' + export_results: false ``` -In this example, the included configuration is added with: +In this example, the inputs for the included configuration are: -- `job-stage` set to `post-deploy`, so the included job runs in the custom `post-deploy` stage. -- `environment` set to `production`, so the included job runs for the production environment. +| Input | Value | Details | +|------------------|-----------------|---------| +| `job-prefix` | `some-service-` | Must be explicitly defined. | +| `job-stage` | `test` | Not defined in `include:inputs`, so the value comes from `spec:inputs:default` in the included configuration. | +| `environment` | `staging` | Must be explicitly defined, and must match one of the values in `spec:inputs:options` in the included configuration. | +| `concurrency` | `2` | Must be a numeric value to match the `spec:inputs:type` set to `number` in the included configuration. Overrides the default value. | +| `version` | `v1.3.2` | Must be explicitly defined, and must match the regular expression in the `spec:inputs:regex` in the included configuration. | +| `export_results` | `false` | Must be either `true` or `false` to match the `spec:inputs:type` set to `boolean` in the included configuration. Overrides the default value. | ### Use `include:inputs` with multiple files @@ -96,7 +143,7 @@ For example: ```yaml include: - - component: gitlab.com/org/my-component@1.0 + - component: gitlab.com/the-namespace/the-project/the-component@1.0 inputs: stage: my-stage - local: path/to/file.yml diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 016b0ae9482..756f14ea5a5 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Format scripts and job logs **(FREE ALL)** diff --git a/doc/ci/yaml/signing_examples.md b/doc/ci/yaml/signing_examples.md index b808edebe7a..e56109085a3 100644 --- a/doc/ci/yaml/signing_examples.md +++ b/doc/ci/yaml/signing_examples.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Sigstore for keyless signing and verification **(FREE SAAS)** @@ -142,7 +142,7 @@ You can use Sigstore and npm, together with GitLab CI/CD, to digitally sign buil CLI provenance generation allows users to trust and verify that the package they are downloading and using is from you and the build system that built it. -For more information on how to publish npm packages, see [GitLab npm Package Registry](../../user/packages/npm_registry/index.md). +For more information on how to publish npm packages, see [GitLab npm package registry](../../user/packages/npm_registry/index.md). ### Sigstore diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md index af275a15f9c..a22e4e322b6 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/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD `workflow` keyword **(FREE ALL)** diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md index 84be9c85676..67383ad8e9e 100644 --- a/doc/ci/yaml/yaml_optimization.md +++ b/doc/ci/yaml/yaml_optimization.md @@ -1,8 +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/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Optimize GitLab CI/CD configuration files **(FREE ALL)** |
