Add latest changes from gitlab-org/gitlab@master

4 files changed, 59 insertions, 31 deletions

diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md
index 583a6401c05..b7247e2251f 100644
--- a/doc/administration/clusters/kas.md
+++ b/doc/administration/clusters/kas.md
@@ -41,7 +41,7 @@ To enable the agent server on a single node:
 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation).
 
 For additional configuration options, see the **Enable GitLab KAS** section of the
-[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template).
+[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/be52c36c243a3422ec38b7d45d459682a07e195f/files/gitlab-config-template/gitlab.rb.template#L1951).
 
 ##### Configure KAS to listen on a UNIX socket
 
diff --git a/doc/development/gems.md b/doc/development/gems.md
index 9259e9f7d50..c061b33b5e4 100644
--- a/doc/development/gems.md
+++ b/doc/development/gems.md
@@ -236,37 +236,61 @@ The project for a new Gem should always be created in [`gitlab-org/ruby/gems` na
 
 1. Determine a suitable name for the gem. If it's a GitLab-owned gem, prefix
    the gem name with `gitlab-`. For example, `gitlab-sidekiq-fetcher`.
-1. Create the gem or fork as necessary.
-1. Ensure the `gitlab_rubygems` group is an owner of the new gem by running:
+1. Locally create the gem or fork as necessary.
+1. [Publish an empty `0.0.1` version of the gem to rubygems.org](https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg) to ensure the gem name is reserved.
+1. Add the [`gitlab_rubygems`](https://rubygems.org/profiles/gitlab_rubygems) and [`gitlab-qa`](https://rubygems.org/profiles/gitlab-qa) users as owners of the new gem by running:
 
    ```shell
    gem owner <gem-name> --add gitlab_rubygems
+   gem owner <gem-name> --add gitlab-qa
    ```
 
-1. [Publish the gem to rubygems.org](https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg)
-1. Visit `https://rubygems.org/gems/<gem-name>` and verify that the gem published
-   successfully and `gitlab_rubygems` is also an owner.
-1. Create a project in [`gitlab-org/ruby/gems` namespace](https://gitlab.com/gitlab-org/ruby/gems/).
-
-   - To create this project:
-       1. Follow the [instructions for new projects](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#creating-a-new-project).
-       1. Follow the instructions for setting up a [CI/CD configuration](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#cicd-configuration).
-       1. Follow the instructions for [publishing a project](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#publishing-a-project).
-   - See [issue #325463](https://gitlab.com/gitlab-org/gitlab/-/issues/325463)
-     for an example.
-   - In some cases we may want to move a gem to its own namespace. Some
-     examples might be that it will naturally have more than one project
-     (say, something that has plugins as separate libraries), or that we
-     expect users outside GitLab to be maintainers on this project as
-     well as GitLab team members.
-
-     The latter situation (maintainers from outside GitLab) could also
-     apply if someone who currently works at GitLab wants to maintain
-     the gem beyond their time working at GitLab.
-
-When publishing a gem to RubyGems.org, also note the section on
-[gem owners](https://about.gitlab.com/handbook/developer-onboarding/#ruby-gems)
-in the handbook.
+1. Optional. Add some or all of the following users as co-owners:
+   - [Marin Jankovski](https://rubygems.org/profiles/marinjankovski)
+   - [Rémy Coutable](https://rubygems.org/profiles/rymai)
+   - [Stan Hu](https://rubygems.org/profiles/stanhu)
+1. Optional. Add any other relevant developers as co-owners.
+1. Visit `https://rubygems.org/gems/<gem-name>` and verify that the gem was published
+   successfully and `gitlab_rubygems` & `gitlab-qa` are also owners.
+1. Create a project in the [`gitlab-org/ruby/gems` group](https://gitlab.com/gitlab-org/ruby/gems/). To create this project:
+    1. Follow the [instructions for new projects](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#creating-a-new-project).
+    1. Follow the instructions for setting up a [CI/CD configuration](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#cicd-configuration).
+    1. Use the [shared CI/CD config](https://gitlab.com/gitlab-org/quality/pipeline-common/-/blob/master/ci/gem-release.yml)
+       to release and publish new gem versions by adding the following to their `.gitlab-ci.yml`:
+
+       ```yaml
+       include:
+         - project: 'gitlab-org/quality/pipeline-common'
+           file: '/ci/gem-release.yml'
+       ```
+
+       This job will handle building and publishing the gem (it uses a `gilab-qa` Rubygems.org
+       API token inherited from the `gitlab-org/ruby/gems` group, in order to publish the gem
+       package), as well as creating the tag, release and populating its release notes by
+       using the
+       [Generate changelog data](../api/repositories.md#generate-changelog-data)
+       API endpoint.
+
+       For instructions for when and how to generate a changelog entry file, see the
+       dedicated [Changelog entries](changelog.md)
+       page.
+       [To be consistent with the GitLab project](changelog.md),
+       Gem projects could also define a changelog YAML configuration file at
+       `.gitlab/changelog_config.yml` with the same content
+       as [in the `gitlab-styles` gem](https://gitlab.com/gitlab-org/ruby/gems/gitlab-styles/-/blob/master/.gitlab/changelog_config.yml).
+    1. To ease the release process, you could also create a `.gitlab/merge_request_templates/Release.md` MR template with the same content
+      as [in the `gitlab-styles` gem](https://gitlab.com/gitlab-org/ruby/gems/gitlab-styles/-/raw/master/.gitlab/merge_request_templates/Release.md)
+      (make sure to replace `gitlab-styles` with the actual gem name).
+    1. Follow the instructions for [publishing a project](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#publishing-a-project).
+
+Notes: In some cases we may want to move a gem to its own namespace. Some
+examples might be that it will naturally have more than one project
+(say, something that has plugins as separate libraries), or that we
+expect users outside GitLab to be maintainers on this project as
+well as GitLab team members.
+The latter situation (maintainers from outside GitLab) could also
+apply if someone who currently works at GitLab wants to maintain
+the gem beyond their time working at GitLab.
 
 ## The `vendor/gems/`
 
diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md
index 5c5970c9a54..a5118eca20c 100644
--- a/doc/user/clusters/agent/gitops/example_repository_structure.md
+++ b/doc/user/clusters/agent/gitops/example_repository_structure.md
@@ -1,14 +1,16 @@
 ---
 stage: Deploy
 group: Environments
-info: A tutorial for structuring a repository for GitOps deployments
+info: A tutorial for deploying a GitLab repository using Flux
 ---
 
-# Tutorial: Structure your repository for GitOps deployments **(FREE)**
+# Tutorial: Deploy a Git repository using Flux **(FREE)**
 
 In this tutorial, you'll create a GitLab project that builds and deploys an application
 to a Kubernetes cluster using Flux. You'll set up a sample manifest project, configure it to
-push manifests to a deployment branch, and configure Flux to sync the deployment branch.
+push manifests to a deployment branch, and configure Flux to sync the deployment branch. With this
+setup, you can run additional steps in GitLab pipelines before Flux picks up the changes
+from the repository.
 
 This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md).
 
diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
index 71f3293fcd8..2ac997b2028 100644
--- a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
+++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
@@ -8,7 +8,9 @@ info: A tutorial for deploying an OCI artifact using Flux
 
 This tutorial teaches you how to package your Kubernetes manifests into an [OCI](https://opencontainers.org/)
 artifact and deploy them to your cluster using Flux. You'll set up a sample manifest project, configure it to
-store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact.
+store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact. With this
+setup, you can run additional steps in GitLab pipelines before Flux picks up the changes 
+from the OCI image.
 
 This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md).