From e74bf51e817ee50e85b1bbdc34f0443d1088fd68 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Thu, 14 Sep 2023 15:10:32 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/ci/components/catalog.md | 4 +-- doc/ci/components/index.md | 61 ++++++++++++++++++++++---------------------- 2 files changed, 32 insertions(+), 33 deletions(-) (limited to 'doc/ci/components') diff --git a/doc/ci/components/catalog.md b/doc/ci/components/catalog.md index 12e795073b7..2194e72d56c 100644 --- a/doc/ci/components/catalog.md +++ b/doc/ci/components/catalog.md @@ -4,11 +4,11 @@ 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 --- -# CI/CD Catalog **(PREMIUM ALL EXPERIMENT)** +# CI/CD catalog **(PREMIUM ALL EXPERIMENT)** > [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), +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. ## Mark a components repository as a catalog resource diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md index 881cb931a0a..e73436522dc 100644 --- a/doc/ci/components/index.md +++ b/doc/ci/components/index.md @@ -4,7 +4,7 @@ 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 --- -# CI/CD Components **(FREE ALL EXPERIMENT)** +# CI/CD components **(FREE ALL EXPERIMENT)** > - Introduced as an [experimental feature](../../policy/experiment-beta-support.md) in GitLab 16.0, [with a flag](../../administration/feature_flags.md) named `ci_namespace_catalog_experimental`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/-/epics/9897) in GitLab 16.2. @@ -13,10 +13,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w This feature is an experimental feature and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/9897) to track future work. Tell us about your use case by leaving comments in the epic. -## Components Repository +## Components repository A components repository is a GitLab project with a repository that hosts one or more pipeline components. -A pipeline component is a reusable single pipeline configuration unit. You can use them to compose +A pipeline 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 component can optionally take [input parameters](../yaml/inputs.md). @@ -160,7 +160,7 @@ Nesting of components is not possible. For example: ## Release a component -To create a release for a CI/CD component, you can use: +To create a release for a CI/CD component, use either: - The [`release`](../yaml/index.md#release) keyword in a CI/CD pipeline. Like in the [component testing example](#test-the-component), you can set a component to automatically @@ -186,19 +186,22 @@ include: stage: build ``` -The component is identified by a unique address in the form `/@`, +The component is identified by a unique address in the form `/@`, where: -- `` matches the GitLab host. +- `` matches the GitLab host. You can only reference components + in the same GitLab instance as your project. - `` is the component project's full path and directory where the component YAML file is located. - `` 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`. + - 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. - Only available if the component has been [released](#release-a-component). - - A branch name, for example `main`. + 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: @@ -212,22 +215,15 @@ the path: - `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. -**Additional details**: - -- You can only reference components in the same GitLab instance as your project. -- If a tag and branch exist with the same name, the tag takes precedence over the branch. -- If a tag is named the same as a commit SHA that exists, like `e3262fdd0914fa823210cdb79a8c421e2cef79d8`, - the commit SHA takes precedence over the tag. - ## Best practices ### Avoid using global keywords -You should try to avoid [global keywords](../yaml/index.md#global-keywords) in a component. +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, you should instead: +As an alternative to global keywords, instead: - Add the configuration directly to each job, even if it creates some duplication in the component configuration. @@ -280,7 +276,7 @@ Instead, you can: ### Replace hard-coded values with inputs -You should avoid hard-coding values in a CI/CD components. Hard-coded values might force +Avoid hard-coding values in CI/CD components. Hard-coded values might force component users to need to review the component's internal details and adapt their pipeline to work with the component. @@ -324,13 +320,13 @@ For example: ### Replace custom CI/CD variables with inputs -When using CI/CD variables in a component, you should evaluate if the `inputs` keyword -should be used instead. Requiring a user to define custom variables to change a component's -behavior should be avoided. You should try to use `inputs` for any component customization. +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. -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 are better validated 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, it's value is empty and there is no 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: @@ -364,10 +360,10 @@ In other cases, CI/CD variables are still preferred, including: ### 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 +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 +You should use at least the `major.minor` format, as this is widely understood. For example, `2.0` or `2.1`. Other examples of semantic versioning: @@ -382,7 +378,7 @@ Other examples of semantic versioning: Testing CI/CD components as part of the development workflow is strongly recommended and helps ensure consistent behavior. -You can test changes in a CI/CD pipeline (like any other project) by creating a `.gitlab-ci.yml` +Test changes in a CI/CD pipeline (like any other project) by creating a `.gitlab-ci.yml` in the root directory. For example: @@ -397,8 +393,8 @@ include: stages: [build, test, release] # Expect `component-job` is added. -# This is an example of testing that the included component works as expected. -# You can leverage GitLab API endpoints or 3rd party tools to inspect data generated by the component. +# 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 @@ -423,7 +419,7 @@ create-release: 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. +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 @@ -434,6 +430,9 @@ can be converted to a CI/CD component: 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. 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. +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). -- cgit v1.2.3