diff options
Diffstat (limited to 'doc/ci/components/index.md')
| -rw-r--r-- | doc/ci/components/index.md | 499 |
1 files changed, 259 insertions, 240 deletions
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). |