Add latest changes from gitlab-org/gitlab@master

2 files changed, 34 insertions, 10 deletions

diff --git a/doc/ci/components/catalog.md b/doc/ci/components/catalog.md
index 2194e72d56c..36ed7065e1c 100644
--- a/doc/ci/components/catalog.md
+++ b/doc/ci/components/catalog.md
@@ -11,15 +11,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 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
+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, this repository is not discoverable. You must mark this project as a catalog resource
-to allow it to be visible in the CI/CD Catalog so other users can discover it.
+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 mark a project as a catalog resource:
+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**.
@@ -30,4 +35,15 @@ Ensure the project has a clear [description](../../user/project/settings/index.m
 as the project description is displayed in the component list in the catalog.
 
 NOTE:
-This action is not reversible.
+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**.
diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md
index e73436522dc..e0379bf783d 100644
--- a/doc/ci/components/index.md
+++ b/doc/ci/components/index.md
@@ -13,13 +13,21 @@ 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.
 
+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 component can optionally take [input parameters](../yaml/inputs.md).
+
+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 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).
+
 ## 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. Use them to compose
-an entire pipeline configuration or a small part of a larger pipeline.
+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.
 
-A component can optionally take [input parameters](../yaml/inputs.md).
+If a component requires different versioning from other components, the component should be migrated to its own components repository.
 
 ## Create a components repository
 
@@ -167,7 +175,7 @@ To create a release for a CI/CD component, use either:
   be released after all tests pass in pipelines for new tags.
 - The [UI for creating a release](../../user/project/releases/index.md#create-a-release).
 
-All released versions of the components are displayed in the CI/CD Catalog
+All released versions of the components are displayed in the [CI/CD Catalog](catalog.md)
 page for the given resource, providing users with information about official releases.
 
 Components [can be used](#use-a-component-in-a-cicd-configuration) without being released,