Add latest changes from gitlab-org/gitlab@master

17 files changed, 164 insertions, 72 deletions

diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md
index 8aa1191c315..28030dccb3b 100644
--- a/doc/administration/geo/replication/faq.md
+++ b/doc/administration/geo/replication/faq.md
@@ -23,7 +23,7 @@ For each project to sync:
 
 1. Geo issues a `git fetch geo --mirror` to get the latest information from the **primary** site.
    If there are no changes, the sync is fast. Otherwise, it has to pull the latest commits.
-1. The **secondary** site updates the tracking database to store the fact that it has synced projects A, B, C, etc.
+1. The **secondary** site updates the tracking database to store the fact that it has synced projects A, B, C, and so on.
 1. Repeat until all projects are synced.
 
 When someone pushes a commit to the **primary** site, it generates an event in the GitLab database that the repository has changed.
@@ -47,7 +47,7 @@ Read the documentation for [Disaster Recovery](../disaster_recovery/index.md).
 
 We currently replicate project repositories, LFS objects, generated
 attachments and avatars, and the whole database. This means user accounts,
-issues, merge requests, groups, project data, etc., will be available for
+issues, merge requests, groups, project data, and so on, will be available for
 query.
 
 ## Can I `git push` to a **secondary** site?
@@ -58,7 +58,7 @@ Yes! Pushing directly to a **secondary** site (for both HTTP and SSH, including
 
 All replication operations are asynchronous and are queued to be dispatched. Therefore, it depends on a lot of
 factors including the amount of traffic, how big your commit is, the
-connectivity between your sites, your hardware, etc.
+connectivity between your sites, your hardware, and so on.
 
 ## What if the SSH server runs at a different port?
 
diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md
index 014ca59e571..a80c293149e 100644
--- a/doc/administration/geo/replication/location_aware_git_url.md
+++ b/doc/administration/geo/replication/location_aware_git_url.md
@@ -88,7 +88,7 @@ routing configurations.
 
    ![Created policy record](img/single_git_created_policy_record.png)
 
-You have successfully set up a single host, e.g. `git.example.com` which
+You have successfully set up a single host, for example, `git.example.com` which
 distributes traffic to your Geo sites by geolocation!
 
 ## Configure Git clone URLs to use the special Git URL
diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md
index ae41599311b..966902a3d74 100644
--- a/doc/administration/geo/replication/security_review.md
+++ b/doc/administration/geo/replication/security_review.md
@@ -60,7 +60,7 @@ from [owasp.org](https://owasp.org/).
   access), but is constrained to read-only activities. The principal use case is
   envisioned to be cloning Git repositories from the **secondary** site in favor of the
   **primary** site, but end-users may use the GitLab web interface to view projects,
-  issues, merge requests, snippets, etc.
+  issues, merge requests, snippets, and so on.
 
 ### What security expectations do the end‐users have?
 
@@ -203,7 +203,7 @@ from [owasp.org](https://owasp.org/).
 ### What data entry paths does the application support?
 
 - Data is entered via the web application exposed by GitLab itself. Some data is
-  also entered using system administration commands on the GitLab servers (e.g.,
+  also entered using system administration commands on the GitLab servers (for example
   `gitlab-ctl set-primary-node`).
 - **Secondary** sites also receive inputs via PostgreSQL streaming replication from the **primary** site.
 
@@ -247,7 +247,7 @@ from [owasp.org](https://owasp.org/).
 ### What encryption requirements have been defined for data in transit - including transmission over WAN, LAN, SecureFTP, or publicly accessible protocols such as http: and https:?
 
 - Data must have the option to be encrypted in transit, and be secure against
-  both passive and active attack (e.g., MITM attacks should not be possible).
+  both passive and active attack (for example, MITM attacks should not be possible).
 
 ## Access
 
diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index 6bf306a625c..d63e927627a 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -327,7 +327,7 @@ Slots where `active` is `f` are not active.
 - When this slot should be active, because you have a **secondary** node configured using that slot,
   log in to that **secondary** node and check the PostgreSQL logs why the replication is not running.
 
-- If you are no longer using the slot (e.g. you no longer have Geo enabled), you can remove it with in the
+- If you are no longer using the slot (for example, you no longer have Geo enabled), you can remove it with in the
   PostgreSQL console session:
 
   ```sql
@@ -378,7 +378,7 @@ This happens on wrongly-formatted addresses in `postgresql['md5_auth_cidr_addres
 ```
 
 To fix this, update the IP addresses in `/etc/gitlab/gitlab.rb` under `postgresql['md5_auth_cidr_addresses']`
-to respect the CIDR format (i.e. `1.2.3.4/32`).
+to respect the CIDR format (that is, `1.2.3.4/32`).
 
 ### Message: `LOG:  invalid IP mask "md5": Name or service not known`
 
@@ -390,7 +390,7 @@ This happens when you have added IP addresses without a subnet mask in `postgres
 ```
 
 To fix this, add the subnet mask in `/etc/gitlab/gitlab.rb` under `postgresql['md5_auth_cidr_addresses']`
-to respect the CIDR format (i.e. `1.2.3.4/32`).
+to respect the CIDR format (that is, `1.2.3.4/32`).
 
 ### Message: `Found data in the gitlabhq_production database!` when running `gitlab-ctl replicate-geo-database`
 
@@ -653,7 +653,7 @@ promotion.
 #### If you are promoting a Geo secondary site running on multiple servers
 
 `gitlab-ctl promotion-preflight-checks` will fail due to the existence of
-`failed` rows in the `geo_design_registry` table. Use the 
+`failed` rows in the `geo_design_registry` table. Use the
 [previous snippet](#design-repository-failures-on-mirrored-projects-and-project-imports) to
 determine the actual replication status of Design repositories.
 
@@ -864,7 +864,7 @@ PostgreSQL instances:
 
 The most common problems that prevent the database from replicating correctly are:
 
-- **Secondary** nodes cannot reach the **primary** node. Check credentials, firewall rules, etc.
+- **Secondary** nodes cannot reach the **primary** node. Check credentials, firewall rules, and so on.
 - SSL certificate problems. Make sure you copied `/etc/gitlab/gitlab-secrets.json` from the **primary** node.
 - Database storage disk is full.
 - Database replication slot is misconfigured.
diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md
index 03908e6fc45..bc4128deb4a 100644
--- a/doc/administration/geo/setup/database.md
+++ b/doc/administration/geo/setup/database.md
@@ -462,10 +462,10 @@ data before running `pg_basebackup`.
 
    - If PostgreSQL is listening on a non-standard port, add `--port=` as well.
    - If your database is too large to be transferred in 30 minutes, you need
-     to increase the timeout, e.g., `--backup-timeout=3600` if you expect the
+     to increase the timeout, for example, `--backup-timeout=3600` if you expect the
      initial replication to take under an hour.
    - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether
-     (e.g., you know the network path is secure, or you are using a site-to-site
+     (for example, you know the network path is secure, or you are using a site-to-site
      VPN). This is **not** safe over the public Internet!
    - You can read more details about each `sslmode` in the
      [PostgreSQL documentation](https://www.postgresql.org/docs/12/libpq-ssl.html#LIBPQ-SSL-PROTECTION);
diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md
index 62b258afcf3..3ec84f1268b 100644
--- a/doc/administration/geo/setup/external_database.md
+++ b/doc/administration/geo/setup/external_database.md
@@ -57,7 +57,7 @@ developed and tested. We aim to be compatible with most external
 
 To set up an external database, you can either:
 
-- Set up [streaming replication](https://www.postgresql.org/docs/12/warm-standby.html#STREAMING-REPLICATION-SLOTS) yourself (for example AWS RDS, bare metal not managed by Omnibus, etc.).
+- Set up [streaming replication](https://www.postgresql.org/docs/12/warm-standby.html#STREAMING-REPLICATION-SLOTS) yourself (for example AWS RDS, bare metal not managed by Omnibus, and so on).
 - Perform the Omnibus configuration manually as follows.
 
 #### Leverage your cloud provider's tools to replicate the primary database
diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md
index 2f5d366f927..37415468517 100644
--- a/doc/administration/maintenance_mode/index.md
+++ b/doc/administration/maintenance_mode/index.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9.
 
-Maintenance Mode allows administrators to reduce write operations to a minimum while maintenance tasks are performed. The main goal is to block all external actions that change the internal state, including the PostgreSQL database, but especially files, Git repositories, Container repositories, etc.
+Maintenance Mode allows administrators to reduce write operations to a minimum while maintenance tasks are performed. The main goal is to block all external actions that change the internal state, including the PostgreSQL database, but especially files, Git repositories, Container repositories, and so on.
 
 Once Maintenance Mode is enabled, in-progress actions finish relatively quickly since no new actions are coming in, and internal state changes are minimal.
 In that state, various maintenance tasks are easier, and services can be stopped completely or be
diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md
index 8b9ba55bd3c..2aa95a2b0f1 100644
--- a/doc/administration/monitoring/prometheus/gitlab_metrics.md
+++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md
@@ -344,7 +344,7 @@ These client metrics are meant to complement Redis server metrics.
 These metrics are broken down per [Redis
 instance](https://docs.gitlab.com/omnibus/settings/redis.html#running-with-multiple-redis-instances).
 These metrics all have a `storage` label which indicates the Redis
-instance (`cache`, `shared_state` etc.).
+instance (`cache`, `shared_state`, and so on).
 
 | Metric                            | Type    | Since | Description |
 |:--------------------------------- |:------- |:----- |:----------- |
diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md
index cbbfdf54ad5..c4ff19ec3ea 100644
--- a/doc/administration/nfs.md
+++ b/doc/administration/nfs.md
@@ -10,7 +10,7 @@ type: reference
 NFS can be used as an alternative for object storage but this isn't typically
 recommended for performance reasons.
 
-For data objects such as LFS, Uploads, Artifacts, etc., an [Object Storage service](object_storage.md)
+For data objects such as LFS, Uploads, Artifacts, and so on, an [Object Storage service](object_storage.md)
 is recommended over NFS where possible, due to better performance.
 
 File system performance can impact overall GitLab performance, especially for
diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md
index d3019e2c580..598baa4fcc7 100644
--- a/doc/administration/operations/sidekiq_memory_killer.md
+++ b/doc/administration/operations/sidekiq_memory_killer.md
@@ -25,7 +25,7 @@ minute of delay for incoming background jobs.
 
 Some background jobs rely on long-running external processes. To ensure these
 are cleanly terminated when Sidekiq is restarted, each Sidekiq process should be
-run as a process group leader (e.g., using `chpst -P`). If using Omnibus or the
+run as a process group leader (for example, using `chpst -P`). If using Omnibus or the
 `bin/background_jobs` script with `runit` installed, this is handled for you.
 
 ## Configuring the MemoryKiller
@@ -80,4 +80,4 @@ The MemoryKiller is controlled using environment variables.
   If the process hard shutdown/restart is not performed by Sidekiq,
   the Sidekiq process is forcefully terminated after
   `Sidekiq.options[:timeout] + 2` seconds. An external supervision mechanism
-  (e.g. runit) must restart Sidekiq afterwards.
+  (for example, runit) must restart Sidekiq afterwards.
diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md
index 508d284b0bd..374eebeb773 100644
--- a/doc/administration/operations/ssh_certificates.md
+++ b/doc/administration/operations/ssh_certificates.md
@@ -41,11 +41,11 @@ uploading user SSH keys to GitLab entirely.
 How to fully set up SSH certificates is outside the scope of this
 document. See [OpenSSH's
 `PROTOCOL.certkeys`](https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD)
-for how it works, and e.g. [RedHat's documentation about
+for how it works, for example [RedHat's documentation about
 it](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sec-using_openssh_certificate_authentication).
 
 We assume that you already have SSH certificates set up, and have
-added the `TrustedUserCAKeys` of your CA to your `sshd_config`, e.g.:
+added the `TrustedUserCAKeys` of your CA to your `sshd_config`, for example:
 
 ```plaintext
 TrustedUserCAKeys /etc/security/mycompany_user_ca.pub
@@ -58,7 +58,7 @@ used for GitLab consider putting this in the `Match User git` section
 (described below).
 
 The SSH certificates being issued by that CA **MUST** have a "key ID"
-corresponding to that user's username on GitLab, e.g. (some output
+corresponding to that user's username on GitLab, for example (some output
 omitted for brevity):
 
 ```shell
@@ -77,7 +77,7 @@ $ ssh-add -L | grep cert | ssh-keygen -L -f -
         [...]
 ```
 
-Technically that's not strictly true, e.g. it could be
+Technically that's not strictly true, for example, it could be
 `prod-aearnfjord` if it's a SSH certificate you'd normally log in to
 servers as the `prod-aearnfjord` user, but then you must specify your
 own `AuthorizedPrincipalsCommand` to do that mapping instead of using
@@ -107,13 +107,13 @@ command="/opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell username-{KE
 ```
 
 Where `{KEY_ID}` is the `%i` argument passed to the script
-(e.g. `aeanfjord`), and `{PRINCIPAL}` is the principal passed to it
-(e.g. `sshUsers`).
+(for example, `aeanfjord`), and `{PRINCIPAL}` is the principal passed to it
+(for example, `sshUsers`).
 
 You need to customize the `sshUsers` part of that. It should be
 some principal that's guaranteed to be part of the key for all users
 who can log in to GitLab, or you must provide a list of principals,
-one of which is present for the user, e.g.:
+one of which is present for the user, for example:
 
 ```plaintext
     [...]
@@ -131,7 +131,7 @@ principal is some "group" that's allowed to log into that
 server. However with GitLab it's only used to appease OpenSSH's
 requirement for it, we effectively only care about the "key ID" being
 correct. Once that's extracted GitLab enforces its own ACLs for
-that user (e.g. what projects the user can access).
+that user (for example, what projects the user can access).
 
 So it's OK to e.g. be overly generous in what you accept, since if the
 user e.g. has no access to GitLab at all it just errors out with a
diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index a9ebcfc9fba..4ad3136408b 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -265,6 +265,8 @@ To disable a feature flag that has been enabled for a specific project you can r
 
 You cannot selectively disable feature flags for a specific project/group/user without applying a [specific method of implementing](index.md#selectively-disable-by-actor) the feature flags.
 
+If a feature flag is disabled via chatops, that will take precedence over the `default_enabled` value in the YML. In other words, you could have a feature enabled for on-premise installations but not for GitLab.com.
+
 ### Feature flag change logging
 
 #### ChatOps level
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
index 397153a0abb..ca830ca54b9 100644
--- a/doc/development/feature_flags/index.md
+++ b/doc/development/feature_flags/index.md
@@ -5,15 +5,15 @@ group: Development
 info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
 ---
 
-# Developing with feature flags
+# Feature flags in the development of GitLab
 
 **NOTE**:
 The documentation below covers feature flags used by GitLab to deploy its own features, which **is not** the same
 as the [feature flags offered as part of the product](../../operations/feature_flags.md).
 
 This document provides guidelines on how to use feature flags
-in the GitLab codebase to conditionally enable features
-and test them.
+for the development of GitLab to conditionally and/or incrementally enable features
+and test them in production/staging.
 
 WARNING:
 All newly-introduced feature flags should be [disabled by default](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development).
@@ -21,6 +21,8 @@ All newly-introduced feature flags should be [disabled by default](https://about
 NOTE:
 This document is the subject of continued work as part of an epic to [improve internal usage of Feature Flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). Raise any suggestions as new issues and attach them to the epic.
 
+For an [overview of the feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flag-lifecycle), or if you need help deciding [if you should use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) or not, please see the [feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle) handbook page.
+
 ## When to use feature flags
 
 Moved to the ["When to use feature flags"](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) section in the handbook.
@@ -30,18 +32,18 @@ Moved to the ["When to use feature flags"](https://about.gitlab.com/handbook/pro
 The following highlights should be considered when deciding if feature flags
 should be leveraged:
 
-- By default, the feature flags should be **off**.
+- The feature flag must be **disabled by default**.
 - Feature flags should remain in the codebase for as short period as possible
   to reduce the need for feature flag accounting.
-- The person operating with feature flags is responsible for clearly communicating
-  the status of a feature behind the feature flag with responsible stakeholders. The
+- The person operating the feature flag is responsible for clearly communicating
+  the status of a feature behind the feature flag in the documentation and with other stakeholders. The
   issue description should be updated with the feature flag name and whether it is
   defaulted on or off as soon it is evident that a feature flag is needed.
-- Merge requests that make changes hidden behind a feature flag, or remove an
+- Merge requests that introduce a feature flag, update its state, or remove them
   existing feature flag because a feature is deemed stable must have the
   ~"feature flag" label assigned.
-- When development of a feature will be spread across multiple merge
-  requests, you can use the following workflow:
+
+When the feature implementation is delivered among multiple merge requests:
 
   1. [Create a new feature flag](#create-a-new-feature-flag)
      which is **off** by default, in the first merge request which uses the flag.
@@ -76,24 +78,51 @@ Choose a feature flag type that matches the expected usage.
 ### `development` type
 
 `development` feature flags are short-lived feature flags,
-used so that unfinished code can be deployed in production.
+used for deploying unfinished code to production. Most feature flags used at
+GitLab are the `development` type.
+
+A `development` feature flag must have a rollout issue
+created from the [Feature Flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md).
+
+The format for `development` feature flags is `Feature.<state>(:<dev_flag_name>)`.
+To enable and disable them, run on the GitLab Rails console:
+
+```ruby
+# To enable it for the instance:
+Feature.enable(:<dev_flag_name>)
+
+# To disable it for the instance:
+Feature.disable(:<dev_flag_name>)
+
+# To enable for a specific project:
+Feature.enable(:<dev_flag_name>, Project.find(<project id>))
+
+# To disable for a specific project:
+Feature.disable(:<dev_flag_name>, Project.find(<project id>))
+```
 
-A `development` feature flag should have a rollout issue,
-ideally created using the [Feature Flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md).
+To check a `development` feature flag's state:
 
-This is the default type used when calling `Feature.enabled?`.
+```ruby
+# Check if the feature flag is enabled
+Feature.enabled?(:dev_flag_name)
+
+# Check if the feature flag is disabled
+Feature.disabled?(:dev_flag_name)
+```
+
+For `development` feature flags, the type doesn't need to be specified (they're the default type).
 
 ### `ops` type
 
 `ops` feature flags are long-lived feature flags that control operational aspects
 of GitLab product behavior. For example, feature flags that disable features that might
-have a performance impact, like special Sidekiq worker behavior.
+have a performance impact such as Sidekiq worker behavior.
 
 `ops` feature flags likely do not have rollout issues, as it is hard to
 predict when they are enabled or disabled.
 
-To use `ops` feature flags, you must append `type: :ops` to `Feature.enabled?`
-invocations:
+To invoke `ops` feature flags, you must append `type: :ops`:
 
 ```ruby
 # Check if feature flag is enabled
@@ -112,7 +141,7 @@ push_frontend_feature_flag(:my_ops_flag, project, type: :ops)
 
 An `experiment` feature flag should conform to the same standards as a `development` feature flag,
 although the interface has some differences. An experiment feature flag should have a rollout issue,
-ideally created using the [Experiment Tracking template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/experiment_tracking_template.md). More information can be found in the [experiment guide](../experiment_guide/index.md).
+created using the [Experiment Tracking template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/experiment_tracking_template.md). More information can be found in the [experiment guide](../experiment_guide/index.md).
 
 ## Feature flag definition and validation
 
@@ -179,9 +208,24 @@ type: development
 default_enabled: false
 ```
 
+All newly-introduced feature flags must be [**disabled by default**](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development).
+
+Features that are developed and merged behind a feature flag
+should not include a changelog entry. The entry should be added either in the merge
+request removing the feature flag or the merge request where the default value of
+the feature flag is set to enabled. If the feature contains any database migrations, it
+*should* include a changelog entry for the database changes.
+
 NOTE:
 To create a feature flag that is only used in EE, add the `--ee` flag: `bin/feature-flag --ee`
 
+### Risk of a broken master (main) branch
+
+WARNING:
+Feature flags **must** be used in the MR that introduces them. Not doing so causes a
+[broken master](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) scenario due
+to the `rspec:feature-flags` job that only runs on the `master` branch.
+
 ## Delete a feature flag
 
 See [cleaning up feature flags](controls.md#cleaning-up) for more information about
@@ -290,8 +334,11 @@ end
 
 ### Frontend
 
-Use the `push_frontend_feature_flag` method which is available to all controllers that inherit from `ApplicationController`. You can use
-this method to expose the state of a feature flag, for example:
+When using a feature flag for UI elements, make sure to _also_ use a feature
+flag for the underlying backend code, if there is any. This ensures there is
+absolutely no way to use the feature until it is enabled.
+
+Use the `push_frontend_feature_flag` method which is available to all controllers that inherit from `ApplicationController`. You can use this method to expose the state of a feature flag, for example:
 
 ```ruby
 before_action do
diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md
index 0733a08b9d9..a85ffdd1feb 100644
--- a/doc/integration/jira/index.md
+++ b/doc/integration/jira/index.md
@@ -17,21 +17,18 @@ can use one or both depending on the capabilities you need. It is recommended th
 After you set up one or both of these integrations, you can cross-reference activity
 in your GitLab project with any of your projects in Jira.
 
-<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be).
-
 ### Jira integration
 
 This integration connects one or more GitLab project to a Jira instance. The Jira instance
 can be hosted by you or in [Atlassian cloud](https://www.atlassian.com/cloud).
 The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`.
-To simplify administration, we recommend that a GitLab group maintainer or group owner
-(or instance administrator in the case of self-managed GitLab) set up the integration.
 
-- *If your installation uses Jira Cloud,* use the
-  [GitLab for Jira app](connect-app.md).
-- *If either your Jira or GitLab installation is self-managed,* use the
-  [Jira DVCS Connector](dvcs.md).
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be).
+
+To set up the integration, [configure the project settings](development_panel.md#configure-gitlab) in GitLab.
+You can also configure these settings at a [group level](../../user/admin_area/settings/project_integration_management.md#manage-group-level-default-settings-for-a-project-integration),
+and for self-managed GitLab, at an [instance level](../../user/admin_area/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration).
 
 ### Jira development panel integration
 
@@ -40,6 +37,13 @@ connects all GitLab projects under a group or personal namespace. When configure
 relevant GitLab information, including related branches, commits, and merge requests,
 displays in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/).
 
+To set up the Jira development panel integration:
+
+- *If your installation uses Jira Cloud,* use the
+  [GitLab for Jira app](connect-app.md).
+- *If either your Jira or GitLab installation is self-managed,* use the
+  [Jira DVCS Connector](dvcs.md).
+
 ### Direct feature comparison
 
 | Capability | Jira integration | Jira Development panel integration |
diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md
index c4484ea609f..2f3d705c1fe 100644
--- a/doc/subscriptions/self_managed/index.md
+++ b/doc/subscriptions/self_managed/index.md
@@ -39,7 +39,7 @@ for each tier, see the
 
 A GitLab self-managed subscription uses a hybrid model. You pay for a subscription
 according to the maximum number of users enabled during the subscription period.
-For instances that aren't offline or on a closed network, the maximum number of
+For instances that are offline or on a closed network, the maximum number of
 simultaneous users in the GitLab self-managed installation is checked each quarter,
 using [Seat Link](#seat-link).
 
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index 67024f0a816..1f794bac37f 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -9,17 +9,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1.
 
 The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network
-connectivity between GitLab Runner and a cluster. In the current iteration, only CI/CD jobs in the Configuration project
-are able to access one of the configured agents. GitLab Runner does not have to be running in the same cluster.
+connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster.
 
-Prerequisistes:
+Only CI/CD jobs set in the configuration project can access one of the configured agents.
+
+Prerequisites:
 
 - A running [`kas` instance](index.md#set-up-the-kubernetes-agent-server).
-- A [Configuration repository](index.md#define-a-configuration-repository) with an Agent config file installed (`.gitlab/agents/<agent-name>/config.yaml`).
+- A [configuration repository](index.md#define-a-configuration-repository) with an Agent config file
+  installed (`.gitlab/agents/<agent-name>/config.yaml`).
 - An [Agent record](index.md#create-an-agent-record-in-gitlab).
 - The agent is [installed in the cluster](index.md#install-the-agent-into-the-cluster).
 
-To create the Tunnel:
+To access your cluster from a CI/CD job through the tunnel:
 
 1. In your `.gitlab-ci.yml` add a section that creates a `kubectl` compatible configuration file (`kubecontext`) and use it in one
    or more jobs:
@@ -27,34 +29,39 @@ To create the Tunnel:
    ```yaml
    variables:
      AGENT_ID: 4 # agent id that you got when you created the agent record
+     KUBE_CFG_FILE: "$CI_PROJECT_DIR/.kubeconfig.agent.yaml"
 
    .kubectl_config: &kubectl_config
      - |
-       cat << EOF > "$CI_PROJECT_DIR/.kubeconfig.agent.yaml"
+       cat << EOF > "$KUBE_CFG_FILE"
        apiVersion: v1
        kind: Config
        clusters:
-       - cluster:
-           server: https://kas.gitlab.com/k8s-proxy
-         name: agent
+       - name: agent
+         cluster:
+           server: https://kas.gitlab.com/k8s-proxy/
        users:
        - name: agent
          user:
            token: "ci:$AGENT_ID:$CI_JOB_TOKEN"
        contexts:
-       - context:
-         cluster: agent
+       - name: agent
+         context:
+           cluster: agent
            user: agent
-           name: agent
        current-context: agent
        EOF
 
    deploy:
+     image:
+       name: bitnami/kubectl:latest
+       entrypoint: [""]
      script:
      - *kubectl_config
-     - kubectl --kubeconfig="$CI_PROJECT_DIR/.kubeconfig.agent.yaml" get pods
+     - kubectl --kubeconfig="$KUBE_CFG_FILE" get pods
    ```
 
 1. Execute `kubectl` commands directly against your cluster with this CI/CD job you just created.
 
-We are [working to automate the first step](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) to simplify the process.
+We are working on [creating the configuration file automatically](https://gitlab.com/gitlab-org/gitlab/-/issues/324275)
+to simplify the process.
diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md
index adedee7e731..bdaae4b8225 100644
--- a/doc/user/infrastructure/index.md
+++ b/doc/user/infrastructure/index.md
@@ -89,7 +89,7 @@ tools or rely on 3rd party solutions to streamline their IaC workflows.
 
 Read more on setting up and [using the merge request integrations](mr_integration.md).
 
-## The GitLab terraform provider
+## The GitLab Terraform provider
 
 WARNING:
 The GitLab Terraform provider is released separately from GitLab.
@@ -105,3 +105,35 @@ is available as part of the official Terraform provider documentations.
 ## Create a new cluster through IaC
 
 Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](clusters/connect/new_gke_cluster.md).
+
+## Troubleshooting
+
+### `gitlab_group_share_group` resources not detected when subgroup state is refreshed
+
+The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources
+due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428).
+This results in an error when running `terraform apply` because Terraform attempts to recreate an
+existing resource. 
+
+For example, consider the following group/subgroup configuration:
+
+```plaintext
+parent-group
+├── subgroup-A
+└── subgroup-B
+```
+
+Where:
+
+- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`.
+- `subgroup-A` is shared with `subgroup-B`.
+- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups.
+
+When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the
+details of `subgroup-B` in the `shared_with_groups` array. This leads to the error.
+
+To workaround this issue, make sure to apply one of the following conditions:
+
+1. The `terraform-user` creates all subgroup resources.
+1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`.
+1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project.